Shopify CLI 教程：安装、主题开发命令与 CI/CD 自动部署

更新于 2026-10 · 基于 Shopify CLI 4.x（npm 当前版本 4.9.0）与 shopify.dev 官方文档 整理

Shopify CLI 不是”可选的效率工具”，而是 Shopify 主题和应用开发的唯一官方入口。 在后台代码编辑器里改 Liquid 没有版本控制、没有本地预览、没有回滚；用 CLI 后，你得到的是：本地改代码 → 开发主题实时热更新 → Git 管理 → 一条命令推送到店铺。

网上大量中文教程还停留在 CLI 2.x 时代（shopify auth whoami、theme generate section、@shopify/theme 包、Node 16），这些命令在 3.0+ 已不存在或已变更，照着做必然报错。本文按 2026 年 10 月的官方文档重新核对了每条命令。

一、Shopify CLI 是什么，谁需要它

Shopify CLI 是官方开源的命令行工具（GitHub：Shopify/cli ），命令格式统一为 shopify [topic] [command]，覆盖三类工作：

你需要 CLI 的判断标准：

一句话原则：只要你改的是代码而不是设置，就该用 CLI + Git，而不是后台编辑器。

二、安装 Shopify CLI（Windows / macOS / Linux）

2.1 环境要求（官方当前要求）

最常见的坑：Node 版本过低。旧教程写的 Node 16/18 已不满足 4.x 的要求，安装能成功但运行时报错。建议用 nvm（macOS / Linux）或 nvm-windows / fnm 管理 Node 版本。

2.2 安装命令

# npm（推荐，三平台通用）
npm install -g @shopify/cli@latest
 
# yarn
yarn global add @shopify/cli@latest
 
# pnpm
pnpm install -g @shopify/cli@latest

macOS 也可以用 Homebrew：

brew tap shopify/shopify
brew install shopify-cli

验证安装：

shopify version
shopify help

注意：旧教程里的 npm install -g @shopify/cli @shopify/theme 是 3.x 早期写法，现在只需安装 @shopify/cli 一个包。GitHub releases 下载二进制、shopify-cli-windows-amd64.exe 这类方法属于已停止维护的 2.x，不要再用。

2.3 自动升级（CLI 4.0 起）

从 CLI 4.0 开始，CLI 会通过你安装时使用的包管理器自动升级（CI 环境、项目内本地安装和大版本升级除外）。

shopify upgrade                    # 立即升级
shopify config autoupgrade status  # 查看自动升级状态
shopify config autoupgrade off     # 关闭自动升级（之后每天提示一次新版本）
shopify config autoupgrade on      # 重新开启

团队项目如果需要锁定版本，建议把 CLI 作为项目 devDependency 安装，而不是依赖全局自动升级。

2.4 国内网络 / 公司代理

CLI 3.78+ 支持通过环境变量走代理：

export SHOPIFY_HTTP_PROXY=http://proxy.example.com:8080
# 可选：HTTPS 走另一个代理，不设置则沿用 HTTP 代理
export SHOPIFY_HTTPS_PROXY=https://secure-proxy.example.com:8443
# 带认证的代理
export SHOPIFY_HTTP_PROXY=http://username:password@proxy.example.com:8080

npm 安装慢可以临时切换镜像源，但装完后建议切回官方源，避免自动升级时拉到不同步的版本。

三、登录与店铺连接

CLI 3.0+ 没有单独的 shopify auth whoami、list-stores 命令了。正确流程是：直接运行一个需要店铺权限的命令，CLI 会自动弹出浏览器让你登录。

# 第一次连接时指定店铺，之后的命令会记住这个店铺
shopify theme dev --store my-store
 
# 查看当前连接的是哪个店铺
shopify theme info
 
# 切换账号：先登出，下次运行命令时重新登录
shopify auth logout

三种认证方式怎么选

红线：不要把店主账号密码交给外包。给协作者账号（见 协作者权限设置）或 Theme Access 密码，项目结束即可单独撤销。

四、主题开发命令速查

所有 shopify theme 命令都要在符合 Shopify 主题目录结构的文件夹里运行（assets、blocks、config、layout、locales、sections、snippets、templates）。

4.1 常用命令表

4.2 开发主题（development theme）的规则

shopify theme dev 会创建一个开发主题，它有几条容易踩坑的规则：

• 不占主题数量上限，后台主题库里看不到；
• 7 天不活跃自动删除；
• 运行 shopify auth logout 时会被删除——如果要给客户一个长期可用的预览链接，用 shopify theme share 或 shopify theme push --unpublished；
• 默认会用本地文件覆盖开发主题；如果你在后台主题编辑器里调过设置并想同步回本地，加 --theme-editor-sync；
• 本地预览地址无法预览结账页定制。

4.3 日常开发流程

# 1. 拉取线上主题作为起点（首次）
shopify theme pull --store my-store --live
 
# 2. 本地开发，浏览器打开 http://127.0.0.1:9292
shopify theme dev
 
# 3. 提交前做静态检查
shopify theme check
 
# 4. 推送到一个未发布主题，给客户 / 同事验收
shopify theme push --unpublished
 
# 5. 验收通过后在后台或用命令发布
shopify theme publish --theme 123456789012

4.4 用 profile 和 console 定位慢页面

# 分析商品页 Liquid 渲染耗时，打开火焰图
shopify theme profile --url /products/your-product
 
# 在真实店铺数据上试 Liquid
shopify theme console --url /products/your-product

theme profile 是排查”首页 / 集合页服务器响应慢”的第一工具：火焰图里横条最宽的 snippet 或 section，就是该优先优化的地方。更多性能方法见 Liquid 性能优化。

4.5 .shopifyignore：不想同步的文件

在主题根目录创建 .shopifyignore，支持文件名、通配符和正则：

templates/product.temp.json
config/*_secret.json
*.jpg
/\.(txt|gif|bat)$/

强烈建议把 config/settings_data.json 和 templates/*.json 是否忽略想清楚：这些文件保存着运营在后台编辑器里的配置，本地 push 会覆盖线上的设置。多人协作时，通常用 --ignore 或 --only 精确控制推送范围。

红线：不要在没有备份的情况下对线上主题执行 shopify theme push --live --allow-live。先 theme duplicate 或 theme pull 留一份，再推送。

五、shopify.theme.toml：多店铺 / 多环境配置

如果你要在开发店、测试主题、生产主题之间来回切，每次都敲 --store --theme --password 会出错。官方方案是在主题根目录建 shopify.theme.toml：

[environments.default]
store = "my-dev-store"
 
[environments.staging]
store = "my-store"
theme = "123456789012"
password = "shptka_xxxxxxxx"
ignore = ["config/settings_data.json"]
 
[environments.production]
store = "my-store"
password = "shptka_xxxxxxxx"
live = true
allow-live = true

使用：

shopify theme dev                    # 自动使用 [environments.default]
shopify theme push -e staging        # -e 是 --environment 的简写
shopify theme push -e production

参数优先级：命令行参数 > 环境变量（如 SHOPIFY_FLAG_STORE）> shopify.theme.toml。

check、delete、info、list、publish、pull、push、rename、share 支持同时传多个环境，例如一次推送到多个店铺：

shopify theme push -e store-us -e store-eu

注意：shopify.theme.toml 里如果写了 Theme Access 密码，必须加进 .gitignore，或改用环境变量注入。

六、应用开发命令速查

部署前先跑 shopify app config validate，能在上线前发现 shopify.app.toml 的配置错误。完整的应用开发流程见 Shopify 应用开发指南。

七、Store 命令：脚本化执行 Admin GraphQL

这是 CLI 近期新增的一组命令，适合不想专门写一个 App，又需要批量查询或修改店铺数据的场景（商品批量调整、数据导出、迁移核对）。

# 1. 用指定权限对店铺授权（保存在线 access token 供后续复用）
shopify store auth --store my-store.myshopify.com --scopes read_products,write_products
 
# 2. 执行查询（默认只允许 query，禁止 mutation）
shopify store execute --store my-store.myshopify.com \
  --query 'query { shop { name } products(first: 5) { nodes { title handle } } }'
 
# 3. 从文件读取查询和变量，结果写入文件
shopify store execute --store my-store.myshopify.com \
  --query-file ./queries/products.graphql \
  --variable-file ./queries/vars.json \
  --output-file ./out/products.json
 
# 4. 确认要修改数据时，才显式加 --allow-mutations
shopify store execute --store my-store.myshopify.com \
  --query-file ./mutations/update-price.graphql --allow-mutations

其他可用命令：store graphiql（本地 GraphiQL 界面）、store bulk execute / status / cancel（批量操作）、store info、store list、store create dev（创建开发店）。

红线：--allow-mutations 默认关闭是有原因的。对生产店铺跑 mutation 前，先在开发店验证，并把 --scopes 控制在最小必要范围。token 过期或权限不够时，重新运行 store auth 即可。

八、CI/CD：用 GitHub Actions 自动部署主题

官方推荐的认证方式是 Theme Access 密码，不需要任何人的账号登录。

第一步：在店铺安装 Theme Access 应用，生成密码（以 shptka_ 开头）。

第二步：在 GitHub 仓库 Settings → Secrets 中添加 SHOPIFY_FLAG_STORE（如 my-store.myshopify.com）和 SHOPIFY_CLI_THEME_TOKEN。

第三步：添加工作流 .github/workflows/deploy-theme.yml：

name: Theme deploy
 
on:
  push:
    branches: [main]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
 
      - name: Install Shopify CLI
        run: npm install -g @shopify/cli
 
      - name: Theme Check
        run: shopify theme check --fail-level error
 
      - name: Upload theme
        env:
          SHOPIFY_CLI_THEME_TOKEN: ${{ secrets.SHOPIFY_CLI_THEME_TOKEN }}
          SHOPIFY_FLAG_STORE: ${{ secrets.SHOPIFY_FLAG_STORE }}
          SHOPIFY_FLAG_FORCE: 1
        run: shopify theme push --json --theme 123456789012

一句话原则：CI 推送到指定的未发布主题 ID，人工在后台点发布。不要让流水线直接 --live --allow-live，一次错误合并就会直接改掉线上店铺。

旧教程里的 SHOPIFY_CLI_TOKEN、node-version: '16'、actions/checkout@v2 都已过时，请按上面的写法替换。

九、常见报错与排查

排查时加 --verbose 查看详细日志（注意：详细日志可能包含敏感信息，不要直接贴到公开社区）。

十、FAQ

Q1：Shopify CLI 免费吗？需要 Shopify Plus 吗？ A：完全免费且开源，任何套餐都能用。你只需要一个店铺（或免费的开发店）以及有 Themes 权限的账号。

Q2：Shopify CLI 支持 Windows 吗？ A：支持。Windows 用 npm / yarn / pnpm 全局安装即可，前提是 Node.js 22.12+ 和 Git 2.28+；Homebrew 安装方式仅限 macOS。

Q3：shopify theme dev 会影响线上店铺吗？ A：不会。它上传的是隐藏的开发主题，访客看不到，也不占主题数量上限。只有 push --live、publish 这类命令才会改动线上主题。

Q4：后台主题编辑器的改动怎么同步到本地？ A：运行 shopify theme pull 拉取对应主题；如果正在 theme dev，可加 --theme-editor-sync 让编辑器改动实时写回本地文件。

Q5：旧教程里的 shopify auth login、theme generate section 还能用吗？ A：theme generate 是 CLI 2.x 命令，3.0+ 已移除，新建 Section 直接在 sections/ 目录新建 .liquid 文件。登录不需要手动执行，运行任何需要店铺权限的命令时 CLI 会自动引导登录；切换账号用 shopify auth logout。

Q6：给外包开发者权限，用 CLI 应该给什么？ A：优先给协作者账号（带 Themes 权限）或 Theme Access 密码，不要给店主账号。Theme Access 密码可以单独撤销，最适合短期合作和 CI 使用。

延伸阅读

• 开发环境搭建：Node.js、Git、VS Code 与 Shopify Liquid 插件配置
• Shopify 主题本地开发实战：从拉取线上主题到上线的完整流程
• 主题开发工作流程：分支、预览主题与发布规范
• 主题工程化配置：构建工具、代码规范与自动化
• 测试与部署：Theme Check、预览验收与回滚
• Shopify 应用开发指南：shopify app 命令背后的完整应用架构

小结：2026 年用 Shopify CLI，记住三件事——Node 22.12+ 只装 @shopify/cli 一个包；日常用 theme dev 开发、push --unpublished 验收、人工发布；多店铺用 shopify.theme.toml，CI 用 Theme Access 密码。命令与参数以 Shopify CLI 官方文档 当前版本为准。