Shopify theme package 教程：Dawn 打包实测与上传前检查
主题文件改完以后，下一步通常不是直接上传，而是先得到一个结构正确、可以复核的 ZIP。Shopify CLI 提供的 theme package 正是为这一步准备的：它从本地主题目录读取允许进入主题包的内容，再根据主题名称和版本生成压缩包。
这篇不是只抄命令说明。我用 Shopify CLI 4.7.0 对一个 Dawn 16.0.0 工作副本执行了完整打包，并检查了 ZIP 内的文件数量、顶层目录、自定义 Section、压缩包大小和 SHA-256。下面把这次 Shopify theme package 实测过程整理成可重复的步骤。
Shopify theme package 适合解决什么问题
shopify theme package 会把本地主题整理为可以上传到 Shopify 的 ZIP。它和 theme push 的用途不同：前者只在本地生成文件，不会把主题推送到商店；后者会连接商店并同步主题文件。
- 交付主题给客户前，生成一份确定的压缩包；
- 在上传主题库前，确认包内没有混入仓库文件；
- 在 CI 中保留可下载、可校验的构建产物；
- 为某次上线记录文件大小和校验值，方便之后追踪。
如果本地代码还没有做静态检查，建议先完成 Shopify Theme Check。打包成功只说明 ZIP 被生成，不等于主题代码没有错误，也不等于真实商店页面已经通过功能测试。
本次实测环境和结果
本次使用 Windows 环境、Shopify CLI 4.7.0 和 Dawn 16.0.0。工作副本保留了此前实际添加的 sections/szymwp-key-points.liquid，因此可以顺便验证自定义 Section 是否进入压缩包。主题目录的分工可以先参考 Dawn 主题目录结构。
- 输出文件：
Dawn-16.0.0.zip - 压缩包大小：1,186,980 字节，约 1.13 MiB
- ZIP 条目：354 个
- SHA-256：
B47FA5AD58F3253DAC62063D2CB02DA040CC02C24E0C486A90D117BC0D4CDDCC - 自定义 Section：已包含
layout/theme.liquid：已包含README.md与.github：未包含
包内顶层包含 assets、config、layout、locales、sections、snippets 和 templates。Dawn 这次还包含一个根目录的 release-notes.md，所以不要简单假设 ZIP 只能出现目录；最终应以实际清单为准。
第一步：确认 CLI 和主题目录
先在终端确认 Shopify CLI 版本：
shopify version然后检查即将打包的路径。一个可上传的常规主题至少应使用 Shopify 支持的主题目录结构，其中 layout/theme.liquid 是关键文件。主题使用构建工具时，应把 --path 指向已经完成编译、真正准备上传的输出目录，而不是随手指向源码仓库根目录。
theme/
├── assets/
├── blocks/
├── config/
├── layout/
├── locales/
├── sections/
├── snippets/
└── templates/blocks 并不是每个旧主题都一定存在，但当前 Shopify 主题架构已经支持独立的 theme blocks。没有使用该能力时，不要为了让目录看起来完整而创建空文件。
第二步：执行 Shopify theme package
在主题目录中运行：
shopify theme package也可以在其他位置明确传入路径：
shopify theme package --path ./theme这个命令不需要选择商店，也不会发布主题。实测成功时，终端返回生成位置：
Your local theme was packaged in .../Dawn-16.0.0.zip文件名来自 config/settings_schema.json 中的 theme_name 和 theme_version。本次配置是 Dawn 与 16.0.0，因此输出为 Dawn-16.0.0.zip。如果生成的名称不符合预期，先检查主题信息，不要在每次构建后手工改名来掩盖配置问题。
{
"name": "theme_info",
"theme_name": "Dawn",
"theme_version": "16.0.0"
}第三步：不要只看“打包成功”
Shopify theme package 返回成功以后，我还会做四项检查。
1. 检查核心文件
展开 ZIP 清单，至少确认 layout/theme.liquid、配置文件、正在使用的模板，以及本次修改过的 Section 或 snippet 都存在。本次自定义的 sections/szymwp-key-points.liquid 已进入压缩包。
2. 检查仓库文件是否混入
Dawn 工作副本中存在 .git、.github、README.md、LICENSE.md 和开发配置。本次 ZIP 没有包含 .git、.github 与 README.md。这说明打包命令不是简单地把整个文件夹压缩，但仍应检查清单，而不是靠经验猜测。
3. 记录大小和校验值
文件大小可以帮助发现异常资产，SHA-256 则能确认交付文件是否就是审核过的那一份。Windows PowerShell 可以这样计算：
Get-FileHash .Dawn-16.0.0.zip -Algorithm SHA256macOS 或 Linux 可以使用：
shasum -a 256 Dawn-16.0.0.zip4. 再做上传前验证
ZIP 生成后，仍要在开发商店或未发布主题中检查首页、产品页、购物车、主题编辑器设置和手机端。Shopify 对上传主题包还有压缩大小等限制；当前官方主题限制页列出的压缩包上限是 50 MB，但实际项目不应把这个上限当成优化目标。
主题包导入后台后，不要从“上传成功”直接跳到公开发布；可以先按 Shopify 草稿主题预览教程，用真实商品、导航和移动端页面完成上线前复核。
常见问题
需要先登录 Shopify 吗？
单纯执行本地 Shopify theme package 不需要选择商店。涉及 theme push、theme dev 或其他商店操作时，才需要相应的商店访问权限。
为什么 ZIP 名称不对？
先检查 config/settings_schema.json 中的主题信息。名称或版本为空、格式异常，通常说明主题元数据本身需要整理。
可以把整个项目目录直接交付吗？
源码仓库适合版本管理，上传包适合 Shopify 读取，两者职责不同。项目中如果还有构建脚本、设计源文件、测试数据或凭据，更不能把整个仓库直接当成交付 ZIP。
我的实际打包顺序
- 确认工作副本和准备交付的提交；
- 运行 Theme Check，并处理会阻断上线的问题；
- 在真实开发商店预览关键模板；
- 执行
shopify theme package； - 检查 ZIP 的核心文件、异常文件、大小和哈希；
- 把 ZIP、版本号、校验值和测试结论记录在交付说明中。
Shopify theme package 本身很简单，真正有价值的是把它放进一条可追踪的交付流程。这样拿到的不只是“一个能解压的 ZIP”，而是一份和代码状态、检查结果及版本号对应的主题产物。
n如果当前起点是商店里的在线主题，可以先参考 Shopify theme pull 教程，把远程原始快照和本地工作副本分开，再进行 Theme Check 与打包。
nnn官方资料：theme package 命令参考、Theme architecture、Theme limits、Shopify CLI 4.0 Changelog（访问于 2026 年 8 月 26 日；本文实测 Shopify CLI 4.7.0、Dawn 16.0.0）。
