安装并启动开发

0.1 版本要求 Node.js 22.14 或更高版本、Vite 8，并且 PATH 中可以执行 Shopify CLI。Theme Target 必须是至少包含 layout/ 和 snippets/ 的 Shopify Theme 目录。

先把插件安装在实际使用它的项目中，保证 Vite 配置、命令行入口和生成的 Mixer 使用同一版本。

pnpm add -D vite-plugin-shopify-theme

在 vite.config.ts 中提供前端入口：

import { defineConfig } from 'vite'
import shopifyTheme from 'vite-plugin-shopify-theme'

export default defineConfig({
  plugins: [shopifyTheme({ entry: 'src/main.ts' })],
})

第一次进入开发模式前，先生成并暂存生产形态的 Mixer Snippet 和资源。如果 layout/theme.liquid 还没有渲染 Mixer，构建会在 </head> 前插入 {% render 'vite-mixer' %}，因此布局文件也要一并暂存。随后从 Vite 项目根目录启动 Theme Run，并把真实 Theme 目录传给 --path：

shopify-theme build --path theme-frame
git -C theme-frame add snippets/vite-mixer.liquid layout/theme.liquid assets/
git -C theme-frame commit -m "Initialize Vite assets"
shopify-theme dev --path theme-frame --environment development

theme-frame 只是示例目录，必须替换为项目实际的 Theme Target。--environment 是 Shopify CLI 自身的参数，由 Theme Run 原样转交。开发启动只要求 Git index 中已有生产形态的 Mixer；示例中的提交沿用仓库的首次接入流程，首次构建的原因见Mixer 与 Git。

在默认的 devBranches: ["dev"] 下，dev 还要求 Theme Target 当前的 Git 分支名以 dev 开头。团队使用其他分支命名时，按配置边界修改允许列表或设为 false。

开发命令启动后，确认 Shopify CLI 输出的预览地址能够打开、浏览器加载的是 Vite 开发资源而不是生产资源、修改入口源码能够触发更新。若启动被分支检查、Mixer 检查或目标锁阻止，先运行 doctor 并进入故障排查。已有 Shopify dev 进程数量超过阈值时只会告警，不会阻止启动。