主题文件结构详解

先判断问题出现在哪里

Shopify 主题不是一个杂乱无章的代码堆，而是一个有着严格层级和调用规范的“精密仪器”。

核心逻辑是：模块化（Modularity）与数据分离。

在 Online Store 2.0 架构中，Shopify 彻底将“页面结构数据（JSON）”与“页面渲染逻辑（Liquid）”分离开来。理解这 7 个核心文件夹的职责，是你从“会改代码”到“能写主题”的分水岭。

实战步骤

核心目录 1：`layout/` (全局布局)

操作路径：查看 layout/theme.liquid

这是整个网站的“骨架”。所有的页面（首页、产品页、博客页）最终都会被塞进这个骨架里。
它包含了 HTML 的 <head>（引入全局 CSS/JS、Meta 标签）和 <body>。
核心占位符：{{ content_for_layout }}。Shopify 会将具体页面的内容动态注入到这个占位符中。
通常在这里引入全局的 Header（导航栏）和 Footer（页脚）Sections。

核心目录 2：`templates/` (页面模板 - JSON)

文件类型	职责说明	OS 2.0 核心特性
`index.json` (首页)	定义该页面由哪些 Sections 组成，以及它们的排列顺序。	纯 JSON 格式。不包含任何 HTML 或 Liquid 代码。
`product.json` (产品页)	保存商家在后台编辑器中配置的数据（如隐藏了某个区块，修改了某个标题）。	支持创建多个模板（如 `product.vip.json`），为不同产品应用不同排版。

核心目录 3：`sections/` (页面区块)

操作路径：查看 sections/featured-collection.liquid

这是 OS 2.0 的绝对核心。Sections 是可以被商家在后台自由拖拽、排序和配置的独立模块。
一个 Section 文件包含三部分：
- HTML/Liquid：前端渲染结构。
- CSS/JS：该区块专属的样式和交互脚本（按需加载）。
- {% schema %}：定义商家在后台能看到哪些设置选项（如颜色选择器、文本框）。

核心目录 4：`snippets/` (代码片段) 与 `assets/` (静态资源)

操作路径：了解代码复用与资源加载

snippets/：存放可复用的小块代码（如产品卡片 product-card.liquid、SVG 图标）。它们不能在后台独立配置，只能被 Sections 通过 {% render 'snippet-name' %} 调用。
assets/：存放所有的 CSS、JS、图片和字体文件。在 Liquid 中必须使用过滤器调用，如 {{ 'base.css' | asset_url | stylesheet_tag }}，Shopify 会自动将其部署到全球 CDN。

常见误区与处理方法

误区一：在 `templates/` 文件夹中继续使用 `.liquid` 后缀

规避方法：在老旧的 Vintage 主题时代，模板文件是 product.liquid。在 OS 2.0 时代，虽然 Shopify 依然兼容 .liquid 模板，但如果你使用 .liquid 作为模板，该页面将彻底失去“Sections Everywhere（自由拖拽区块）”的功能！商家在后台将无法为该页面添加或移动任何 Sections。在 2026 年开发新主题，templates/ 目录下的所有文件必须是 .json 格式。所有的渲染逻辑必须下放到 sections/ 中去实现。

误区二：把所有的 CSS 和 JS 都塞进 `assets/theme.css` 和 `theme.js`

规避方法：很多新手为了省事，把轮播图、弹窗、倒计时的所有样式和脚本全写在一个全局文件里。这会导致用户访问首页时，被迫下载了只有结账页才用得上的庞大代码，导致首屏加载极慢。OS 2.0 强调“按需加载（Lazy Loading）”。应该将 CSS 和 JS 拆分，直接写在对应的 Section 文件中，或者在 Section 顶部按需引入：{{ 'component-slider.css' | asset_url | stylesheet_tag }}。只有当页面上存在这个 Section 时，代码才会被加载。

误区三：直接修改 `config/settings_data.json` 文件

规避方法：config/ 目录下有两个文件：settings_schema.json（定义全局设置的表单结构）和 settings_data.json（保存商家填写的具体数据）。绝对不要手动去修改 settings_data.json！这个文件是由 Shopify 后台自动生成的，结构极其复杂。如果你手抖多写了一个逗号，会导致整个主题的后台配置面板崩溃，商家将无法修改任何颜色或字体。所有的全局配置数据，必须通过 Shopify 后台的 Theme Editor 可视化界面去修改。

FAQ