调试 Cloud build-failed 部署：用…

当部署因构建失败时，无需推送 tracked branch，在本地 Docker 与项目 Git 仓库中用 mcloud local build 复现并迭代修复构建问题。

适用场景

解决思路

1. 使用 `mcloud local build` 在本地执行 Cloud 构建，复现 Cloud 构建项目的方式；用于调试 `build-failed` 部署，无需推送变更并等待完整 Cloud 构建。
2. 确认本机已安装并运行 Docker，并从项目 Git 仓库内部运行命令。
3. 不要给 `mcloud local build` 传 `--json`；它会流式输出纯文本构建日志，并通过退出码表示结果（`0` 为成功），不要按 JSON 解析其输出。
4. 仅用它复现 `build-failed`（构建）失败，不用于 `deployment-failed`（运行时）失败；运行时失败改用 `mcloud logs --deployment <id>`。
5. 确认 mcloud CLI 版本至少为 v0.1.10。
6. 默认 Docker 构建缓存关闭，以便构建变量变化总能失效缓存；如需启用，传入 `--docker-cache`。
7. 基本命令：`mcloud local build --organization <org-id> --project <project-id-or-handle> --environment <environment-handle>`。
8. 它会从已关联的 Cloud 项目和环境中推断根路径与构建变量；默认构建 backend，传 `--type storefront` 构建 storefront。
9. 使用 `-o/--organization <id>` 指定组织 ID；省略时回退到 active context。
10. 使用 `-p/--project <id-or-handle>` 指定项目 ID 或 handle；省略时回退到 active context。
11. 使用 `-e/--environment <handle>` 指定使用哪个环境的变量；省略时回退到 active context。
12. 使用 `-t/--type <backend|storefront>` 指定构建类型，默认 `backend`。
13. 使用 `--root-path <path>` 指定相对于仓库根目录的 backend 根路径；省略时自动推断；如果找不到 Cloud 项目则为 `.`。
14. 使用 `--storefront-path <path>` 为 `--type storefront` 指定相对于仓库根目录的 storefront 路径；省略时自动推断。
15. 使用 `--env-file <path>` 改用本地 `.env` 文件，而不是 Cloud 环境变量。
16. 使用 `-v/--var <KEY=VALUE>` 覆盖单个构建变量，可重复传入。
17. 使用 `--docker-cache` 启用 Docker 构建缓存，默认 `false`。
18. 成功后（退出码 `0`），backend 镜像标记为 `<repository-name>:cloud-local-build-<commit-hash>`；storefront 构建会写出输出目录并打印路径。
19. 失败时（非零退出码），命令以失败步骤的错误退出；像调试 Cloud 构建一样调试该错误。
20. 复现构建失败时，先找到失败的部署及其构建的 commit：运行 `DEPLOYMENT_ID=$(mcloud deployments list --json | jq -r '[.[] | select(.backend_status == "build-failed")][0].id')`。
21. 获取该部署的 commit：`COMMIT=$(mcloud deployments get "$DEPLOYMENT_ID" --json | jq -r '.commit_hash')`。
22. 检出该 commit 以使本地构建匹配：`git checkout "$COMMIT"`。
23. 根据退出码分支：运行 `if mcloud local build; then echo "Build succeeded locally; failure not reproducible from this commit."; else echo "Build failed locally; inspect the streamed output for the failing step."; fi`。
24. 本地构建一旦以 `0` 退出，将修复推送到 tracked branch，并用 `mcloud environments trigger-build <env>` 启动新的 Cloud 构建。
25. 示例：复现 active context 的 backend 构建：`mcloud local build`。
26. 示例：复现 storefront 构建：`mcloud local build --type storefront --storefront-path apps/storefront`。
27. 示例：不编辑代码测试构建变量修复：`mcloud local build --var NODE_ENV=production`。
28. 示例：基于本地 `.env` 文件构建：`mcloud local build --env-file .env`。
29. 示例：复用 Docker 缓存以加快重建：`mcloud local build --docker-cache`。

适用边界 · 注意事项

• `deployment-failed` 等运行时失败不要用它，改用 `mcloud logs --deployment <id>`。
• 未安装并运行 Docker，或不在项目 Git 仓库内时无法使用。
• 未安装 mcloud CLI v0.1.10+，或无法访问对应 Cloud 项目/环境时无法使用。