Shopify Theme Check 使用教程：Dawn 实测与 CI 阈值
Shopify Theme Check 是检查 Liquid 和 JSON 主题代码的官方工具。它不会替你证明页面已经在真实商店里正常运行，但能在上传主题之前发现语法、未定义对象、废弃写法和部分性能问题。本文不只列命令：我用 Shopify CLI 4.7.0 对本地 Dawn 16.0.0 跑了两轮检查，记录默认阈值与严格阈值为何会得到不同退出码。
这次 Shopify Theme Check 实测了什么
测试目录来自我此前拆解过的 Dawn 主题。本地副本基于 Dawn 16.0.0、Git 提交 258f00f，另外保留了本站 Section 实作文件，因此结果代表这个具体工作目录，不应直接当成所有 Dawn 16.0.0 副本的统一结论。
| 项目 | 本次环境 |
|---|---|
| 操作系统 | Windows |
| Shopify CLI | 4.7.0 |
| 主题 | Dawn 16.0.0 |
| Dawn 提交 | 258f00f |
| 默认检查结果 | 0 error、11 warning、退出码 0 |
--fail-level warning | 同样 11 个 warning、退出码 1 |
这里最值得注意的不是“有 11 个警告”，而是同一份代码在不同失败阈值下可以返回不同退出码。如果准备把 Theme Check 放进 GitHub Actions 或其他 CI 流程，必须先明确团队要阻止 error，还是连 warning 也要阻止。
先确认 Shopify CLI 与主题目录
Shopify 当前文档要求安装 Node.js 22.12 或更高版本，并通过 npm、Yarn、pnpm 或 Homebrew 安装 Shopify CLI。已经安装时先检查版本；命令不存在时再升级或重新安装，不必为了 Theme Check 先登录商店。
node --version
shopify version
shopify theme check --helpTheme Check 是静态代码分析。只要本地目录是完整主题结构，运行 theme check 本身不需要把主题上传到商店。需要真实商店数据、预览链接和热更新时，才进入 shopify theme dev 的登录与开发主题流程。关于目录之间怎样参与渲染，可以先看本站的 Shopify Dawn 主题目录结构。
运行第一次完整检查
进入主题根目录后直接运行：
shopify theme check如果终端当前不在主题目录，可显式指定路径。这样更适合自动脚本，也能减少“检查了错误目录”的误判：
shopify theme check --path ./dawn需要保存机器可读结果时使用 JSON 输出：
shopify theme check --path ./dawn --output json我的工作目录返回 8 个涉及文件，共计 11 个 warning、0 个 error。警告包含 OrphanedSnippet、VariableName、UnusedAssign 和 UndefinedObject。默认失败级别为 error，因此这轮命令退出码仍然是 0。
为什么有 warning，命令仍然成功
--fail-level 决定从哪个严重级别开始让命令以非零状态结束。默认值是 error，所以只有 warning 并不会让默认检查失败。如果 CI 要求 warning 也必须处理，可以运行：
shopify theme check --path ./dawn --fail-level warning我对同一目录执行这条命令后，报告内容仍是 0 error 和 11 warning，但退出码变成 1。这证明退出码不仅取决于问题数量，还取决于你设置的失败阈值。
| 使用场景 | 建议命令 |
|---|---|
| 本地日常检查 | shopify theme check |
| 保存 JSON 报告 | shopify theme check -o json |
| CI 阻止 error | shopify theme check --fail-level error |
| CI 连 warning 也阻止 | shopify theme check --fail-level warning |
| 查看启用的检查项 | shopify theme check --list |
warning 应该怎么处理
不要看到 warning 就批量关闭检查，更不要直接把 --auto-correct 当成“全部修复”。我通常按下面顺序判断：
- 先读检查名称和文件位置：确认它指向自己的改动、上游 Dawn 文件，还是仅在特定渲染上下文中成立的对象。
- 再判断是否影响运行：Liquid 语法错误与未知标签应优先处理；命名风格或可能未使用的变量需要结合调用链判断。
- 只做可解释的修改：若修改会改变商品、购物车或 Section 行为，应在开发主题中继续预览和回归测试。
- 最后才考虑局部忽略：确实属于工具无法理解的上下文时，用精确注释或配置限定范围，并在代码审查中写明原因。
例如 UndefinedObject 不一定等于线上必然报错。某些对象可能由 Section、layout 或运行环境提供，而静态分析无法完整推导。相反，自己新写的 snippet 报 UnusedAssign，通常就值得回到调用链确认变量是否真的遗漏。本站的 Shopify Liquid snippet 与 render 参数实作展示了如何把变量来源写得更清楚。
用 .theme-check.yml 管理项目规则
项目需要长期维护时，可以在主题根目录添加 .theme-check.yml。官方配置支持继承推荐规则、忽略目录，以及按检查项设置启用状态、严重级别和文件范围。先让 CLI 生成基础配置：
shopify theme check --init下面是一个刻意保持简单的示例：
extends:
- theme-check:recommended
ignore:
- node_modules/**
UnusedAssign:
severity: warning如果主题源文件会先从 src 构建到 dist，应通过 root 指向真正需要检查的输出目录。不要用大范围 ignore 掩盖第三方或历史代码；排除范围越大，Theme Check 能提供的保护越少。
把 Theme Check 放进实际开发流程
Theme Check 最适合放在三个位置：
- 写 Liquid、Section 或 snippet 时，在本地随时运行；
- 提交 Git 前运行一次完整检查；
- 在 CI 中用明确的
--fail-level阻止不符合团队规则的合并。
它不能替代真实预览。Theme Check 通过后，仍要在开发主题中检查 Section 配置、Block 排序、商品数据、购物车行为和手机端布局。若正在做可视化模块，可以结合本站的 Shopify Section 和 Block 实作继续测试编辑器行为。
几个常见问题
运行 Shopify Theme Check 必须登录商店吗？
检查本地完整主题目录时不需要商店登录。涉及 theme dev、theme pull、theme push 等商店操作时才需要相应权限和认证。
0 error 是否代表主题可以直接上线？
不是。它只说明当前规则没有发现达到 error 级别的问题。真实数据、交互、兼容性、性能和移动端仍需在预览商店中验证。
可以直接使用 –auto-correct 吗？
可以先在独立 Git 分支尝试，但必须审查 diff 并重新测试。自动修正只适合工具能确定的改动，无法替代对业务逻辑和主题结构的判断。
本次结论
Shopify Theme Check 的核心价值不是追求一张“全绿”报告，而是把 Liquid 和 JSON 的静态问题提前到上传之前。本次 Dawn 目录在默认 error 阈值下以 0 退出，在 warning 阈值下以 1 退出，说明 CI 配置必须明确失败级别。先修真正影响运行的问题，再对需要保留的上下文警告做小范围、可解释的配置，比全局关闭检查更可靠。
静态检查完成后，如果要把审核过的工作副本整理成可上传 ZIP，可以继续看 Shopify theme package 教程。
如果你正在为集合页设置每页商品数量，可以继续看 Shopify Liquid paginate 与 Dawn 分页实测，里面记录了 PaginationSize 阈值从 60 调回 24 的前后结果。
官方资料：Shopify Theme Check 概览、Shopify CLI theme check 命令参考、Theme Check 配置说明、Shopify CLI 4.0 更新日志（访问日期：2026 年 8 月 25 日；实测环境：Shopify CLI 4.7.0、Dawn 16.0.0，提交 258f00f）
