@lute/shopify-plugin-sync

一个 Shopify CLI 插件，用于按 git diff 推送 / 拉取 Shopify 主题文件，参考 shopkeeper 的 oclif plugin 架构搭建。

灵感来源于 push-changed.js 脚本，将其能力封装成可复用的 Shopify CLI 子命令。

特性

• 按 git ref 推送差异：HEAD~N / 单 commit / a..b 范围 / 未提交工作区
• 环境选择器：从 shopify.theme.toml 自动解析 [environments.*]，支持参数或交互式
• commit 提示：未提交模式下交互式确认 commit message（默认值兜底）
• dry-run / no-commit / last：贴近原脚本习惯的辅助 flag
• sync pull：交互选环境后透传给底层 shopify theme pull

安装

作为 Shopify CLI 插件（推荐）

shopify plugins install @lute/shopify-plugin-sync

本地开发链接

git clone <this-repo>
cd shopify-plugin-sync
pnpm install
pnpm build

# 在你的 Shopify 主题项目里
shopify plugins link /path/to/shopify-plugin-sync

本插件使用 tsx 作为 ESM auto-transpile 加载器 （而不是 ts-node），因此 shopify plugins link 不会再提示 "linked ESM module and cannot be auto-transpiled"，改完 src/ 立即生效。

如果你看到该提示，说明本地依赖里残留了 ts-node，重新 pnpm install 即可。

不想用 tsx 的话可走传统循环：终端 A pnpm build:watch，终端 B 跑命令。

独立 CLI

npm i -g @lute/shopify-plugin-sync
mc-sync sync push

前置认证

在执行任何 metafields / metaobjects 命令前，需要先对目标 store 完成授权并申请所需 scope：

shopify store auth --store your-shop.myshopify.com \
  --scopes write_metaobject_definitions,read_metaobject_definitions,write_metaobjects,read_metaobjects,read_products

每个 store 只需执行一次。Token 会由 Shopify CLI 管理，后续命令通过 -s <store> 或 -e <env> 自动使用。

命令

shopify sync push

按 git diff 推送变更文件。

USAGE
  $ shopify sync push [-e <env>] [-r <ref> | --last] [-m <msg>] [--no-commit] [--dry-run] [--path <p>]

FLAGS
  -e, --env=<value>      环境名（来自 shopify.theme.toml）
  -r, --ref=<value>      git ref：HEAD~N / SHA / a..b
      --last             等价 --ref HEAD~1
  -m, --message=<value>  未提交模式下的 commit 文案
      --no-commit        未提交模式下跳过 git commit，仅 push
      --dry-run          只打印 shopify 命令，不执行
      --path=<value>     主题项目路径（默认当前目录）

示例：

# 全交互
shopify sync push

# 直接推 dev 环境的最近一次提交
shopify sync push -e dev --last

# 推某次 commit 的差异到 prod，先 dry-run 看看
shopify sync push -e prod -r abc1234 --dry-run

# 推一段 commit 范围
shopify sync push -e dev -r origin/main..HEAD

shopify sync pull

带环境选择器的 theme pull 包装。

USAGE
  $ shopify sync pull [-e <env>] [--live] [--nodelete] [--only <p>...] [--ignore <p>...] [--path <p>]

示例：

shopify sync pull           # 交互选 env
shopify sync pull -e prod   # 直接拉 prod

shopify sync metafields push

从 JSON 文件推送 metafield definitions（默认 .shopify/metafields-update.json）。全部推送成功后默认会自动删除该文件，可用 --keep-file 保留。

USAGE
  $ shopify sync metafields push [-e <env>] [-s <store>] [-f <file>] [--keep-file] [--path <p>] [--dry-run]

示例：

# 通过环境解析 store
shopify sync metafields push -e dev

# 显式指定 store
shopify sync metafields push -s your-shop.myshopify.com

# 指定自定义文件
shopify sync metafields push -e dev -f .shopify/metafields-update.prod.json

# 推送后保留文件
shopify sync metafields push -s your-shop.myshopify.com -f .shopify/metafields-update.prod.json --keep-file

shopify sync metafields pull

从 Shopify 拉取指定 owner 的 metafield definitions，并写入 JSON 文件（默认 .shopify/metafields-update.json）。输出格式可直接给 shopify sync metafields push 使用。 metaobject_reference / list.metaobject_reference 会保留 validations，其中通常包含 metaobject_definition_id；同时会额外查询并输出 metaobjectDefinition，用于识别具体引用的 Metaobject definition type/name。

USAGE
  $ shopify sync metafields pull [-e <env>] [-s <store>] [-o <owner>...] [-q <query>...] [-f <file>] [--force] [--path <p>] [--dry-run]

FLAGS
  -o, --owner=<value>    可重复。支持 product / collection / shop 等 owner。当所有 --query 都带 owner 前缀时可省略
  -q, --query=<value>    查询过滤器，可重复。支持 owner 前缀格式 product:lute.pdp_config，也支持无前缀的 namespace.key 简写（此时需搭配 --owner）或原始 Shopify 搜索语法 namespace:custom key:seo_title
  -f, --file=<value>     输出文件路径，默认 .shopify/metafields-update.json
      --force            输出文件已存在时允许覆盖指定 owner 的内容

示例：

# 拉 product definitions
shopify sync metafields pull -e dev -o product

# 一次拉多个 owner
shopify sync metafields pull -s your-shop.myshopify.com -o product -o collection --force

# 从不同 owner 精确拉取（owner 前缀写在 -q 里，无需 -o）
shopify sync metafields pull -s your-shop.myshopify.com -q product:lute.pdp_config -q shop:lute.track_info --force

# 只拉 custom namespace 下的 product definitions
shopify sync metafields pull -s your-shop.myshopify.com -o product -q namespace:custom --force

# 组合多个 filter（写在同一个 -q 里表示 AND）
shopify sync metafields pull -s your-shop.myshopify.com -o product -q "namespace:custom key:seo_title" --force

# 按 namespace.key 精确拉取多个 definitions（多次查询，合并结果）
shopify sync metafields pull -s your-shop.myshopify.com -o product -q app.pdp_config -q custom.hide_variant_discount_checkbox --force

# 混合使用：带前缀的 + 不带前缀的（不带前缀的使用 --owner 指定）
shopify sync metafields pull -s your-shop.myshopify.com -o product -q lute.pdp_config -q shop:lute.track_info --force

# 指定输出文件
shopify sync metafields pull -e prod -o product -f .shopify/metafields-update.prod.json --force

shopify sync metaobjects pull

从 Shopify 拉取指定 metaobject entries，写入 JSON 文件（默认 .shopify/metaobjects-pull.json）。支持按 type 拉取全部 entries 或按 handle 拉取单条。会递归解析 metaobject 引用。输出格式可直接给 shopify sync metaobjects push 使用。

USAGE
  $ shopify sync metaobjects pull [-e <env>] [-s <store>] [-t <type>...] [-h <handle>...] [-f <file>] [--force] [--path <p>] [--dry-run]

FLAGS
  -t, --type=<value>     拉取某个 metaobject type 的所有 entries，可重复
  -h, --handle=<value>   按 type.handle 拉取单条 entry，如 pdp_config.my-entry，可重复
  -f, --file=<value>     输出文件路径，默认 .shopify/metaobjects-pull.json
      --force            输出文件已存在时允许覆盖

示例：

# 拉取某个 type 的全部 entries
shopify sync metaobjects pull -e dev --type pdp_config

# 按 handle 拉取单条 entry
shopify sync metaobjects pull -s your-shop.myshopify.com --handle pdp_config.my-entry

# 一次拉多个 type + handle
shopify sync metaobjects pull -e dev --type pdp_config --type guarantee --handle variant_media.my-media

# 指定输出文件，覆盖已有
shopify sync metaobjects pull -s your-shop.myshopify.com --type pdp_config --file .shopify/metaobjects.json --force

shopify sync metaobjects push

从 JSON 文件推送 metaobject entries 到目标 store（默认 .shopify/metaobjects-pull.json）。使用 type.handle 作为匹配键，已存在则更新，不存在则创建。全部推送成功后默认删除源文件。

USAGE
  $ shopify sync metaobjects push [-e <env>] [-s <store>] [-f <file>] [--keep-file] [--path <p>] [--dry-run]

FLAGS
  -f, --file=<value>     输入 JSON 文件路径，默认 .shopify/metaobjects-pull.json
      --keep-file        推送成功后保留输入文件（默认会删除）

示例：

# 通过环境解析 store
shopify sync metaobjects push -e prod --file .shopify/metaobjects-pull.json

# 显式指定 store
shopify sync metaobjects push -s your-shop.myshopify.com --file .shopify/metaobjects-pull.json

# 推送后保留文件
shopify sync metaobjects push -e prod --file .shopify/metaobjects-pull.json --keep-file

# dry-run 查看操作
shopify sync metaobjects push -s your-shop.myshopify.com --dry-run

工作原理

1. 解析项目根目录的 shopify.theme.toml 中的 [environments.*] 列表。
2. 根据 git ref（或工作区）解析受影响的文件清单。
3. 透传调用 shopify theme push -e <env> --only <files>（或 pull）。

详细决策见 plan 文件，源码见 src/。

许可证

MIT