Shopify 主题结构：layout、template、section、block 的关系

主题改不动的多数情况不是代码难，是改错了地方。想给产品页加一段说明却去动 theme.liquid，把该交给设置的文案写死在模板里，改完一种页面，其他页面跟着坏。Shopify 主题的目录分工是明确的，先认清每个目录负责什么，再决定打开哪个文件。

七个目录，一个目录一件事

目录	放什么	改动的影响面
layout	theme.liquid 等骨架文件，公共结构	全站所有页面
templates	按页面类型决定渲染什么，JSON 或 Liquid	该模板类型的所有页面
sections	可配置的内容模块，带 schema	引用它的模板与分组
snippets	被反复引用的代码片段	所有引用它的文件
assets	样式、脚本、图片、字体	引用这些资源的位置
config	主题设置的定义与已保存的值	编辑器面板与使用该值的位置
locales	界面文案与语言词条	前台的界面文本

这张表能解释很多改了半天没效果的情况：动 assets 里的样式，只影响引用它的那几处；动 layout，会连带影响全站包括不该动的地方；一句话写在 sections 里还是写在 locales 里，决定了它能不能被商家改、能不能被翻译。判断一个改动该落在哪个文件，本质上是在判断它的影响范围。

template 与页面类型必须对上

每种页面类型对应一个模板类型。要渲染产品页，主题里至少得有一个 product 模板；要渲染元对象页，就得有对应 metaobject 类型的模板，比如 metaobject/book 这种形式（模板文档）。同一模板类型可以有多个版本，用来区分不同用途，比如给外套类产品单独做一个产品模板，或者给带视频的页面单独做一个页面模板。

模板文件有两种写法，选哪种取决于你要不要 shopify 的可配置模块。JSON 模板是数据文件，页面内容来自它引用的 section，商家可以在主题编辑器里增删和调整顺序；文档的说法很明确，想在模板里使用 section，就应该用 JSON 模板，它还减少了 settings_data.json 里的数据量，主题编辑器的响应因此更好。Liquid 模板可以直接写 HTML 和 Liquid，适合结构固定、不需要商家调整的页面。

JSON 模板有容量上限，全部模板类型合计 1000 个（同一份文档）。对绝大多数店铺这个数字没有实际约束，但如果你打算按品类批量复制产品模板，它会是你第一个撞到的限制；而且在撞上之前，主题编辑器的可维护性通常会先撑不住。

section 给容器，block 给条目

section 是可以被商家定制的可复用内容模块，block 让商家在一个 section 内部添加、删除和重新排序内容（section 文档）。这两个概念经常被混着用，区分方法很简单：一段内容如果商家需要反复添加多份，它是 block；需要整体开关、整体排版，它是 section。

• JSON 模板与 section 分组最多渲染 25 个 section，每个 section 最多 50 个 block。指望每个产品配一个 section，或者一个页面塞四十段，会先撞上限。
• section 通过 section 对象拿自己的设置，block 的设置通过 block 对象拿。section 外部创建的变量在 section 里不可见，section 里的变量也出不去；唯一的例外是在该 section 内部渲染的 snippet 里引用 section 与 block 对象。
• schema 是 section 的必填部分，name、tag、class、limit、settings、blocks、presets、enabled_on、disabled_on 都在这里定义。默认所有模板都能用某个 section，想限制它出现在哪些模板或分组，也写在这里。
• section 可以动态加进 JSON 模板或分组，也可以静态写在模板与骨架里。静态写法适合位置固定的内容，商家仍然能在编辑器里就地改设置。

给 snippet 传设置时用 render 传参，不要指望片段自己能看到外层变量。上面那条作用域规则就是原因，也是很多片段在首页正常、在产品页却是空白的问题根源——它读的是自己看不到的变量，而不是没被引入。

设置值存在哪儿，改错会丢什么

动态 section 的设置与 block 数据存在引用它的 JSON 模板文件里，主题级设置存在 settings_data.json。这意味着修改 schema 里已有设置的 id，会让商家之前保存的值对不上号，界面上出现的是空值或者旧默认值，而且不会报错。要动 id 之前先复制主题，把当前文件留一份再改。

{
  "sections": {
    "main": { "type": "main-product" },
    "faq": {
      "type": "faq-list",
      "settings": { "heading": "常见问题" },
      "blocks": {
        "q1": { "type": "item", "settings": { "title": "多久发货？" } }
      },
      "block_order": ["q1"]
    }
  },
  "order": ["main", "faq"]
}

这段 JSON 模板的结构就三件事：sections 里按 id 存每个模块的类型与数据，block_order 决定 block 的顺序，order 决定 section 在页面上的先后。理解这三层之后，某种页面上模块突然不见这类问题，可以直接对着文件看，不用靠猜。

动手前的四个习惯

1. 复制一份主题，在副本上改，预览确认之后再发布。线上主题不直接编辑代码。
2. 打开文件前先搜它被谁引用：section 的类型名、snippet 的文件名、要改的设置 id，各自出现在哪些模板和片段里。
3. 改 schema 之前，先在主题编辑器里确认有几个模板用到了这个 section，旧数据要不要保留。
4. 删除 snippet 或重写 assets 文件之前，确认没有其他文件在引用它。编辑器的报错会指向出错的文件，不会告诉你谁在调用它。

assets 是另一个容易忽略的地方。同一张首屏大图，写法不同会直接影响加载速度，这属于图片加载策略的问题，首屏图的加载属性与尺寸那一层单独讲。集合页的排序与筛选，以及它们带来的 URL 变化，是 section 与脚本配合的结果，排序丢筛选项的排查就是从这套结构里找原因。

第三方主题要按文件来读

目录构成大体一致，但文件名、section 数量、是否使用 JSON 模板由主题作者决定。官方文档描述的是平台规则，不是某套主题的目录清单；文档与文件对不上时以文件为准，也不要照着官方默认主题的文件名去猜第三方主题里有没有同名 section。

还有一类需求其实不是开发需求，是设置项没找到。改代码之前在主题设置与 section 设置里翻一遍，能省掉的改动比想象中多。真正需要写代码的地方通常集中在三处：模板级元信息的输出、结构化数据的完整性、内链与导航结构，这些属于技术 SEO 的作业面，也是光算谷歌 SEO 服务会一起处理的部分。

主题里最容易影响 SEO 输出的三个位置

主题自身的调整里，只有三个位置会直接影响搜索引擎看到的东西：骨架文件里的公共头部，站点级标题模板、验证标记、语言版本的指向都在那里；模板级元信息的条件输出，每种页面类型输出什么标题与描述；结构化数据的输出位置，由主题还是由应用负责。其余改动基本属于展示层，做得好买家体验更好，做坏了不至于丢页面。

这三个位置有个共同点，输出在页面上看不见。验收方式因此和视觉调整不同，不能用眼睛判断，要打开源码比对。按抓取、索引、选中三层依次检查的清单可以参照技术 SEO 自查清单，每一项的检查位置和通过标准都列在那里。

静态引入和动态加入，看位置是否固定

同一个 section 有两种进入页面的方式。写在 JSON 模板里，商家可以在编辑器里增删和排序；静态写在模板或骨架文件里，位置由代码决定，商家只能在原位改设置。前者的代价是模块可能被误删，后者的代价是调整布局要动代码。

判断标准是位置是否固定，跟内容重要不重要无关。页头的公告条、产品页主图区、页脚前的信任模块，位置通常固定，用静态写法更稳，也不给商家留下删掉关键模块的机会；首页卖点区、图文介绍、常见问题这类需要反复调整顺序的内容，用动态写法。把必须存在的模块做成可以一键删除的形态，是主题里最常见的设计失误。

不用读代码也能看清一套主题的结构

后台的主题文件编辑器可以逐个浏览 layout、templates、sections、snippets、assets、config、locales 这些目录。想快速判断一套主题的可配置程度，不必逐个打开文件，先看三处：sections 目录里的文件数量，决定商家在编辑器里能看到多少种模块；每个 section 的 schema 里 presets 的数量，决定添加时的初始形态；config 里的设置分组，决定主题级设置面板复杂到什么程度。

要知道某个模块出现在哪些页面，反过来搜更省时间：在主题文件里搜 section 的类型名，命中的模板文件就是它的使用位置。这个办法在产品模板和集合模板上尤其好用，这两类模板的分支最多，也最容易出现某个品类页面漏了模块的情况。

边界：平台已经做掉的部分

Shopify 会为店铺自动生成并更新 sitemap，主题默认也带结构化数据输出，这两件事不需要在主题里重做（平台说明见查找与提交 sitemap），改版时反而容易丢。换主题时的冻结与验收清单讲的正是怎么避免这一类损失。

主题只负责把内容渲染出来，内容本身来自产品、集合、页面与元字段。结构清楚的主题不会让文案变好，但结构混乱的主题会让每次改文案都变成一次风险操作。想加一段可复用、非技术人员自己就能维护的内容模块，下一步要写的是自定义 section 的 schema 与预设。