Shopify 主题本地开发实战：用 Shopify CLI 克隆 Dawn、预览、推送和发布

如果你想修改 Shopify 主题，不一定要直接在主题编辑器或在线代码编辑器里操作。

更适合开发的方式是：

本地获取主题代码
        ↓
在 VS Code 中修改
        ↓
使用 Shopify CLI 本地预览
        ↓
实时查看修改效果
        ↓
将主题推送到 Shopify
        ↓
在后台预览和检查
        ↓
确认无误后发布

本文会使用 Shopify CLI 创建一个 Dawn 主题副本，修改首页 Banner 的文字和颜色，然后将主题推送到开发商店，最后发布为当前主题。

这个流程适合什么场景？

使用 Shopify CLI 进行主题开发，适合：

修改 Liquid 模板
开发自定义 Section
编写主题 Snippet
修改 CSS 和 JavaScript
开发 Online Store 2.0 主题
为客户制作专属主题
在发布前进行完整预览
使用 Git 管理主题代码

如果只是修改颜色、字体或区块内容，Shopify Theme Editor 通常已经足够。

如果需要修改以下内容，建议使用 Shopify CLI：

Liquid 结构
主题逻辑
动态区块
自定义模板
复杂 CSS
JavaScript 交互
多环境协作

Shopify CLI 支持主题初始化、本地预览、热更新、Theme Check、推送和发布等开发流程。citation:Partner Program FAQ

开始前的准备

需要准备：

一个 Shopify 商店
Shopify CLI
Node.js 或对应系统的安装工具
Git
VS Code 或其他代码编辑器
一个 Development Store 或用于测试的商店

开发真实商店时，不要直接在当前线上主题上实验。

更安全的流程是：

复制当前线上主题
        ↓
在开发环境修改
        ↓
推送为未发布主题
        ↓
预览和测试
        ↓
确认无误后发布

如果是正式商店，建议先在 Shopify Admin 中复制当前主题，或者下载当前主题作为备份。

安装 Shopify CLI

Shopify CLI 的安装方式根据操作系统不同而不同。

macOS

如果使用 Homebrew，可以根据 Shopify CLI 当前安装说明完成安装。

安装后在终端运行：

shopify

如果能够看到 Shopify CLI 的帮助信息，说明安装成功。

Windows 和 Linux

通常可以通过 Node.js 包管理工具安装 Shopify CLI。

安装后运行：

shopify

确认终端可以识别 Shopify CLI。

不同版本的安装命令可能发生变化，建议以 Shopify 官方当前安装文档为准。

登录 Shopify CLI

第一次运行需要完成 Shopify 账号登录。

可以先运行：

shopify

然后根据终端提示完成登录。

登录成功后，CLI 才能：

访问你的开发商店
创建开发主题
推送主题文件
读取主题列表
发布主题

登录的 Shopify 账号需要拥有对应商店的主题开发权限。

创建本地主题项目

在本地创建一个用于主题开发的目录：

mkdir shopify-themes
cd shopify-themes

如果没有现成的主题 Git 仓库，可以使用：

shopify theme init

CLI 会引导你创建一个新的主题项目，通常可以使用 Dawn 作为起点。

设置项目名称，例如：

my-development-theme

创建完成后，进入主题目录：

cd my-development-theme

打开项目：

code .

如果你的电脑没有配置 code 命令，也可以直接用 VS Code 打开当前文件夹。

认识 Shopify 主题文件结构

一个典型的 Shopify 主题项目包含：

assets/
config/
layout/
locales/
sections/
snippets/
templates/

`assets`

保存主题资源，例如：

CSS
JavaScript
图片
字体
其他前端文件

`config`

保存主题设置：

颜色
字体
布局
Theme Editor 设置

`layout`

保存主题整体布局，例如：

theme.liquid

`sections`

保存可以在 Theme Editor 中添加和配置的主题区块。

例如：

image-banner.liquid
header.liquid
footer.liquid
featured-product.liquid

`snippets`

保存可重复使用的小片段。

`templates`

保存不同页面模板，例如：

index.json
product.json
collection.json
cart.json

`locales`

保存多语言文本。

连接到 Development Store 进行本地预览

在主题项目目录中运行：

shopify theme dev --store your-development-store.myshopify.com

也可以按照 CLI 提示选择目标商店。

启动后，Shopify CLI 通常会：

创建一个开发主题
上传当前本地文件
提供本地预览地址
提供 Theme Editor 预览地址
监听文件变化
自动刷新预览页面

开发主题通常不会直接成为线上主题，因此可以放心进行测试。

处理店铺密码页面

Development Store 可能启用了店铺密码。

如果打开预览地址后看到密码页面，可以在 Shopify Admin 中查看：

Online Store → Preferences

找到店铺密码并复制，然后在预览页面中输入。

如果不知道密码，可以让拥有店铺权限的管理员进入 Preferences 页面查看。

使用热更新修改主题

启动 shopify theme dev 后，可以在 VS Code 中直接修改主题文件。

例如打开：

sections/image-banner.liquid

找到标题输出位置，修改标题内容：

<h2>{{ section.settings.heading }}</h2>

也可以临时修改成：

<h2>Welcome to our store</h2>

保存文件后，浏览器预览页面通常会自动刷新。

这种本地热更新非常适合快速验证：

Liquid 结构
CSS 样式
Section 设置
商品数据
模板逻辑
JavaScript 交互

修改主题样式

主题样式通常位于：

assets/

例如：

base.css
component-slideshow.css
section-image-banner.css

可以在对应 CSS 文件中修改标题颜色：

.banner__heading {
  color: red;
}

保存后回到本地预览页面，检查标题颜色是否发生变化。

开发时建议不要一开始就直接修改大量全局样式。最好：

先确认选择器只影响目标区块
检查桌面端和移动端
检查不同模板
避免覆盖主题原有变量
使用主题已有的颜色系统
完成后运行 Theme Check

使用 Theme Editor 测试区块设置

主题代码中的 Section 设置，会显示在 Shopify Theme Editor 中。

例如，image-banner.liquid 中可能存在：

{
  "type": "text",
  "id": "heading",
  "label": "Heading",
  "default": "Image banner"
}

模板中使用：

{{ section.settings.heading }}

启动开发预览后，可以打开 CLI 提供的 Theme Editor 链接。

然后：

打开对应页面
找到 Image Banner
修改标题文字
保存设置
返回预览页面查看结果

这可以验证：

Section 设置是否生效
section.settings 是否读取正确
Theme Editor 保存的数据是否进入主题
修改后的内容是否在前台显示

主题编辑器中的设置和本地文件修改需要区分：

本地文件
    ↓
控制主题结构和默认值

Theme Editor 设置
    ↓
保存商家的实际主题配置

分享开发主题预览

Shopify CLI 通常会提供一个分享预览链接。

这个链接可以发给：

客户
设计师
团队成员
内容编辑
测试人员

分享预览时，对方看到的是开发主题，不会改变当前线上主题。

需要注意：

预览链接可能会过期
关闭本地开发服务后预览可能失效
预览不是正式发布
预览状态不代表所有设备都已测试

使用 Git 管理主题代码

主题开发建议从第一天开始使用 Git。

初始化仓库：

git init
git add .
git commit -m "Initialize Shopify theme"

每完成一个小功能，就创建一次提交：

git add .
git commit -m "Update homepage banner styles"

推荐的提交粒度是：

修改首页 Banner 颜色
新增商品推荐区块
优化移动端导航
修复购物车页面间距

不要把以下内容提交到公开仓库：

Access Token
Client Secret
私有 API 密钥
商家敏感数据
本地临时文件

如果使用团队协作，建议为不同工作建立分支：

main
development
feature/homepage-banner
feature/product-card

在发布前运行 Theme Check

在推送主题前运行 Theme Check：

shopify theme check

它可以帮助发现：

Liquid 语法错误
未关闭的标签
无效过滤器
可能影响性能的写法
不符合主题规范的代码
无效的 Section 设置

Theme Check 不是完整的视觉测试，但可以提前过滤很多明显问题。

将主题推送到 Shopify

本地预览确认没有问题后，可以将主题推送到 Shopify。

推送为未发布主题

建议第一次推送使用：

shopify theme push --unpublished

这样 Shopify 会创建一个新的草稿主题，不会覆盖当前线上主题。

推送时可以为主题命名：

My Development Theme

推送完成后，进入 Shopify Admin：

Online Store → Themes

在 Draft themes 区域中，应该可以看到刚刚推送的主题。

在后台预览主题

在 Shopify Admin 的 Themes 页面中，可以：

Preview
Customize
Edit code
Publish

建议先点击 Preview，而不是直接 Publish。

预览时检查：

首页
商品页
集合页
搜索页
购物车页
博客页
页面模板
404 页面
移动端显示
多语言显示
不同商品数据

主题发布前，最好使用真实的商品、图片、价格和库存数据进行测试。

发布主题

确认草稿主题没有问题后，可以从 Shopify Admin 发布：

Online Store → Themes

找到 Draft theme，点击：

Publish

Shopify 会让你确认发布。

也可以使用 Shopify CLI 的主题发布命令：

shopify theme publish

然后选择需要发布的主题。

发布主题后，之前的线上主题通常会保留在 Draft themes 区域，方便回滚。citation:Publishing themes

更新已经发布的主题

主题发布后，如果只是进行小范围修改，可以使用：

shopify theme push

推送前确认 CLI 当前指向正确的主题。

建议不要在没有确认目标的情况下直接推送：

shopify theme push

更安全的流程是：

先查看主题列表
        ↓
确认目标主题名称
        ↓
推送到目标主题
        ↓
预览
        ↓
检查移动端和桌面端
        ↓
确认发布

如果只是开发，继续推送到未发布主题会更安全。

如何避免覆盖线上主题

发布主题前，建议执行：

复制当前线上主题

或者先下载一份备份。

推荐工作流：

当前线上主题
        ↓
复制为备份主题
        ↓
本地开发和测试
        ↓
推送新的 Draft theme
        ↓
主题预览
        ↓
团队检查
        ↓
发布新主题

不要在本地开发阶段直接把代码推送到当前线上主题。

主题发布前的测试清单

首页

Banner 标题显示正常
图片比例正常
CTA 按钮可以点击
桌面端布局正常
移动端布局正常

商品页面

商品标题正常
价格显示正常
变体选择正常
商品图片可以切换
加购按钮正常
缺货状态正常

集合页面

商品卡片显示正常
筛选功能正常
排序功能正常
分页或无限加载正常
商品图片没有变形

购物车页面

商品可以删除
数量可以修改
折扣码输入正常
结账按钮正常
空购物车状态正常

性能和代码

运行 Theme Check
检查浏览器 Console
检查图片尺寸
检查 JavaScript 错误
检查 CSS 是否影响其他区块
检查 Liquid 是否产生空输出
检查移动端加载速度

常见问题排查

Shopify CLI 无法识别

检查：

Node.js 是否安装
Shopify CLI 是否安装
终端是否能够运行 shopify
当前账号是否已经登录
CLI 版本是否过旧

`shopify theme init` 无法创建主题

检查：

当前目录是否有写入权限
当前目录是否已经存在同名文件夹
网络连接是否正常
Git 是否可用
是否指定了正确的主题来源

本地预览出现密码页面

进入：

Online Store → Preferences

复制当前店铺密码，然后在预览页面输入。

修改文件后页面没有刷新

检查：

shopify theme dev 是否仍在运行
浏览器是否打开 CLI 提供的预览链接
修改的文件是否属于当前主题
是否修改了未被当前模板引用的 Section
是否需要手动刷新页面

`theme push` 推送错了主题

立即停止继续推送，然后：

检查 Shopify Admin 中的主题列表
确认哪个主题受到影响
恢复之前的备份主题
检查 CLI 当前目标
后续使用未发布主题开发

Theme Editor 中看不到设置

检查：

Section 的 schema 是否正确
section.settings 的 ID 是否一致
Liquid 文件是否使用了正确的设置字段
JSON 模板是否引用了该 Section
当前预览是否打开了正确页面

项目验收清单

完成以下检查后，主题才适合发布：

Shopify CLI 安装成功
Shopify 账号登录成功
主题项目可以初始化
Dawn 或目标主题已经下载
shopify theme dev 可以启动
本地预览页面可以打开
热更新正常
CSS 修改可以生效
Liquid 修改可以生效
Theme Editor 设置可以保存
Theme Check 没有关键错误
代码已经提交到 Git
主题已经推送为未发布版本
首页测试通过
商品页测试通过
集合页测试通过
购物车测试通过
移动端测试通过
主题预览通过
已经备份当前线上主题
发布对象确认无误
主题发布后可以正常访问

结语

使用 Shopify CLI 开发主题，核心不是直接修改线上代码，而是建立一条安全、可重复的开发流程：

本地主题代码
        ↓
Shopify CLI 预览
        ↓
Theme Editor 验证
        ↓
Git 版本管理
        ↓
推送为未发布主题
        ↓
后台预览
        ↓
确认后发布

shopify theme dev 负责快速预览和热更新，shopify theme push 负责将代码推送到 Shopify，shopify theme publish 或 Shopify Admin 负责正式发布。

只要始终遵循：

先本地开发
先推送草稿
先预览测试
最后发布

就可以在不影响线上店铺的情况下，安全地开发和迭代 Shopify 主题。

citation:Partner Program FAQ

citation:Publishing themes

文章目录