故障排查

先运行 doctor --path <theme> 读取插件拥有的状态。需要机器处理时使用 --json，并按 target.structure、mixer.index、layout.render、lock.active 等稳定诊断码分支；不要依赖终端文案做字符串匹配。诊断不会获取或修复目标锁，也不会修改 Git 或连接商店。

Theme Target 无法解析

确认命令从 Vite 项目根目录运行，--path 指向真实的 Theme 根目录，且该目录包含 layout/ 和 snippets/。直接运行 Vite 时，需要在插件选项中提供 themePath；不要假定 Theme Run 的私有上下文会出现在独立 Vite 进程中。两者同时存在时，themePath 必须与 --path 指向同一目标。

开发分支检查失败

在默认的 devBranches: ["dev"] 下，只有 Theme Target 当前分支名以 dev 开头时，dev 才能启动。处于 detached HEAD 或目录没有 Git 仓库时，该检查同样失败。可以切换分支、调整 devBranches，或设为 false。

提示目标正在使用

同一真实 Theme Target 的操作互斥，不同目标才可以并行。先确认记录的进程是否仍在运行。插件能恢复已经消失的持锁进程；若恢复保护本身被强制终止，系统会失败关闭并报告需要人工处理的位置，此时按实际诊断信息处理，不要删除其他目标的锁。

列出已有 shopify theme dev 或 shopify app dev 进程的告警来自 maxDevProcesses。它不会阻止启动，但多个 dev 进程共享同一账号的 API 配额，可能拖慢预览。

Mixer 阻止开发

检查 Mixer 是否已跟踪、Git index 是否保存当前的生产形态，以及版本标记是否匹配已安装的插件。重新运行生产构建、审查差异并暂存生成文件；不要跳过检查或手工复制开发地址。

生产检查失败

build、push 和 package 的验证门会检查 Mixer 是否为生产形态、layout/theme.liquid 是否渲染它，以及标准 Theme 目录中是否残留 /@vite/client 引用。它还会拒绝 assets/*.js 中未解析的构建期别名导入（如 #theme/），以及对 cdn.jsdelivr.net、unpkg.com、cdnjs.cloudflare.com 的引用。修正实际构建或布局问题后重新执行完整命令，不要绕开推送或打包前的验证门。

手机能打开预览但资源失败

分别检查 Shopify 预览和 Vite 来源是否从手机可达，再检查 HTTPS 页面是否加载了局域网 HTTP 资源。按手机与局域网调试重新核对来源选择和网络边界。