English
vite-plugin-shopify-theme
配置边界
区分宿主 Vite 配置、插件职责和 Shopify CLI 参数的边界，列出全部插件选项与默认值，避免直接 Vite 构建与 Theme Run 得到不同结果。
配置时先判断一个值属于宿主项目、插件，还是 Shopify CLI。把三者混在环境文件或包装脚本里，会让直接 Vite 构建和 Theme Run 得到不同结果。
宿主项目负责
- 前端源码入口及其环境选择；
- 源码目录别名；
- Vite 监听地址、端口、HTTPS 或代理；
- CSS、JavaScript 框架及其他 Vite 插件；
- 是否通过动态导入或构建配置拆分代码。
插件不读取项目的环境文件或 shopify.theme.toml。入口需要随环境变量切换时，在 vite.config.ts 中用 Vite 的 loadEnv 读取，再把结果传给 entry。
插件负责
- 解析并约束 Theme Target，包括指向 Theme 根目录的
#theme别名； - 把文件监听范围收窄到 Theme Target 和入口所在源码目录；
- 将构建结果写入 Theme 的
assets/目录，并统一生产文件命名； - 生成开发或生产形态的 Mixer Snippet；
- 管理开发重载、同一 Theme Target 的运行锁、Shopify dev 进程告警和生产检查；
- 在受支持的 Git 工作流中保护开发形态的 Mixer。
插件选项
选项传给 shopifyTheme()。显式传入 undefined 时回退到默认值；允许 false 的选项会保留 false。
| 选项 | 默认值 | 作用 |
|---|---|---|
entry | 必填 | Vite root 内的入口文件，可写 root 相对路径或绝对路径 |
themePath | — | Theme 根目录，可相对当前工作目录或写绝对路径；直接运行 vite 时必填，Theme Run 通过私有运行上下文提供 |
snippet | "vite-mixer.liquid" | 生成的 Mixer Snippet 文件名 |
devBranches | ["dev"] | 允许运行 dev 的分支名前缀，任一命中即通过；false 关闭检查 |
worktree | "skip" | "skip" 用 skip-worktree 管理已跟踪的 Mixer；"off" 不做任何 Git 操作 |
reload | [] | 额外触发整页刷新的目录（相对 root）；false 关闭插件的整页刷新，例如改用 Shopify CLI 自带的 live reload |
devOrigin | "local" | 写入开发形态 Mixer 的 Vite 来源："local"、"network" 或完整的 HTTP(S) 来源 |
maxDevProcesses | 0 | 已存在的 Shopify dev 进程数超过该值时告警；false 关闭检查 |
debug | false | 开启调试日志，只从该选项读取 |
Shopify CLI 负责
商店身份、认证、远端 Theme、Shopify 环境（environments）和 Shopify 原生命令参数仍由 Shopify CLI 解释。Theme Run 只解析自身命令与本地 Theme 路径，其余适用参数转交 Shopify CLI。
以已安装版本为准时，查看产品仓库的选项表。修改配置后分别验证开发和生产构建，不要只以开发服务器能够启动作为完成标准。