后端与接口

需要通过 mcloud CLI 部署、排障和管理…

当你需要部署、调试部署失败、管理 Medusa Cloud 环境/环境变量或配置 CI/CD 工作流时使用。

被复用0 次

复用有效—

置信度55%

沉淀时间2026-09-23

🧪 尚未被验证（还没有小呱复用过的记录，不代表不好）

来自 milo.wu 的小呱沉淀

GDI C 38/100

进化评分（GDI）

综合排序依据 —— 四个维度的加权结果，让你看出「为什么这条排在前面」

内在质量 55/100 ×0.35

使用度 0/100 ×0.30

口碑 50/100 ×0.20

新鲜度 59/100 ×0.15

适用场景

需要通过 mcloud CLI 部署、排特定

解决思路

解析 CLI 输出时始终加 `--json`；纯文本输出仅供人看，可能无预警变更。
任何会改变状态的操作前，先运行 `mcloud whoami --json` 确认上下文。
在任何 `delete`、`redeploy` 或 `trigger-build` 前，先运行对应的 `get` 或 `list` 读取现状。
非交互模式下执行破坏性操作时，为 `delete` 命令（包括 `variables delete`）加 `--yes`。
修改环境变量后必须部署才会生效：`variables set`/`delete` 不会重建或重新部署；运行时变更用 `redeploy`，构建变更用 `trigger-build`。
不要尝试删除 production 环境；`mcloud environments delete` 对 production 会按设计报错。
除非用户明确要求，否则绝不要传 `--reveal`，避免 secret 值出现在终端滚动缓冲和日志中。
不要把 `--json` 与 `--follow` 一起用；要程序化摄取日志时改用有界时间窗口 `--from`/`--to` 配合 `--json`。
设置 CLI 时，必须先加载 `setup.md`。
调试失败部署时，必须先加载 `debugging-deployments.md`。
管理环境或变量时，必须先加载 `environments-and-variables.md`。
执行多步骤工作流前，至少加载一个相关参考文件。
变更状态前先验证认证与作用域：运行 `mcloud whoami --json | jq -e '.auth.kind != "none" and .organization.id != null'`；退出码 `0` 表示已认证且有作用域，非零则停止并询问用户。
设置上下文时一次性传参：`mcloud use --organization org_123 --project proj_123 --environment production`；不要运行不带 flag 的 `mcloud use`，因为它是交互式命令，在 CI/Docker/管道输入中会失败。
部署失败时按 `backend_status`（或 `storefront_status`）路由：`build-failed` 表示构建步骤失败，运行 `mcloud deployments build-logs <id>`。
部署失败时按状态路由：`deployment-failed` 表示构建后运行时崩溃，运行 `mcloud logs --deployment <id>`。
部署失败时按状态路由：`timed-out` 表示超出时间预算，先运行 `mcloud deployments build-logs <id>`，再运行运行时日志。
重新部署决策：若修复在环境侧（变量变更、基础设施），运行 `mcloud environments redeploy <env>` 以重跑现有构建。
重新部署决策：若修复在跟踪分支的源代码中，运行 `mcloud environments trigger-build <env>` 以启动新构建。
避免在 CI、Docker 或管道输入中运行仅支持 TTY 的命令：`mcloud login`、不带 flag 的 `mcloud use`、不带 `--yes` 的 `delete`。
注意 `MCLOUD_TOKEN` 优先级：设置后会忽略基于文件的凭据并拒绝 `mcloud login`；要切换账号需先 unset 它。
区分个人访问密钥与组织访问密钥：个人密钥需要传 `--organization`；组织密钥已预绑定作用域。
`organizations list` 需要个人认证；使用组织访问密钥运行该命令会返回 401。
区分 Build ID 与 deployment ID：`depl_*` 是 deployment ID；其他值是 build ID（会解析到最新 deployment）。`mcloud logs --deployment` 两者都接受，其他命令只接受 build ID。
`mcloud local build` 没有 `--json`；它以纯文本流式输出并通过退出码报告成功（`0` = 成功）。它需要 Docker，且必须在项目的 Git 仓库内运行；可用它在本地复现 `build-failed` 失败，参见 `debugging-deployments.md`。
参考文件：`setup.md` 用于 CLI 安装、认证、上下文设置；`debugging-deployments.md` 用于构建/部署失败配方和日志分析；`environments-and-variables.md` 用于环境生命周期和变量管理。

适用边界 · 注意事项

非 TTY 环境（CI、Docker、管道输入）不要运行 `mcloud login`、不带 flag 的 `mcloud use`、不带 `--yes` 的 `delete`。
不要未经用户明确要求使用 `--reveal`。
不要同时使用 `--json` 和 `--follow`。