mcloud-local

用途

mcloud local 是 Medusa Cloud CLI（mcloud）中的本地命令，用于在本机执行 Cloud 构建，模拟 Cloud 平台构建项目的方式。它的典型用途是调试 build-failed（构建失败）的部署：不必把改动推送到被跟踪分支并等待一次完整的云端构建，就能在本地快速定位失败步骤。该命令自 mcloud CLI v0.1.10 起提供。

主要能力

local build：在本地运行一次 Cloud 构建。它会从已关联的 Cloud 项目和环境中推断根路径与构建变量。默认构建后端；传入 --type storefront 时构建店面。

命令形式：

mcloud local build \
  --organization <org-id> \
  --project <project-id-or-handle> \
  --environment <environment-handle>

选项：

-o/--organization <id> — 组织 ID（回退到当前活动上下文）
-p/--project <id-or-handle> — 项目 ID 或 handle（回退到当前活动上下文）
-e/--environment <handle> — 使用其变量的环境（回退到当前活动上下文）
-t/--type <backend|storefront> — 构建类型（默认 backend）
--root-path <path> — 后端根路径，相对于仓库根目录（省略时自动推断；未找到 Cloud 项目时为 .）
--storefront-path <path> — 店面路径，相对于仓库根目录，用于 --type storefront（省略时自动推断）
--env-file <path> — 使用本地 .env 文件代替 Cloud 环境的变量
-v/--var <KEY=VALUE> — 覆盖单个构建变量，可重复传入
--docker-cache — 启用 Docker 构建缓存（默认 false）

输出：

成功时（退出码 0），后端镜像会被打上标签 <repository-name>:cloud-local-build-<commit-hash>；店面构建会写出其输出目录并打印该路径。
失败时（退出码非零），命令以失败步骤的错误退出——按调试 Cloud 构建的方式调试即可。

约束与限制

没有 --json 标志：local build 以纯文本流式输出构建日志，并通过退出码表示结果（0 表示成功）。不要将其输出解析为 JSON。
需要本机已安装并运行 Docker，且必须在项目的 Git 仓库内运行。
只能复现 build-failed（构建）失败，不能复现 deployment-failed（运行时）失败。对于运行时失败，应使用 mcloud logs --deployment <id>。
默认禁用 Docker 构建缓存，以保证变量变更总能触发缓存失效；如需启用，传入 --docker-cache。

使用方式：复现一次构建失败

先检出失败部署所构建的同一个提交，使本地构建与之匹配，然后根据退出码判断：

# 识别失败的部署及其构建的提交
DEPLOYMENT_ID=$(
  mcloud deployments list --json \
    | jq -r '[.[] | select(.backend_status == "build-failed")][0].id'
)
COMMIT=$(mcloud deployments get "$DEPLOYMENT_ID" --json | jq -r '.commit_hash')

git checkout "$COMMIT"

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

本地构建以 0 退出后，即可把修复推送到被跟踪分支，并用 mcloud environments trigger-build <env> 启动一次新的 Cloud 构建。

示例

# 复现当前活动上下文的后端构建
mcloud local build

# 复现店面构建
mcloud local build --type storefront --storefront-path apps/storefront

# 在不修改代码的情况下测试某个构建变量的修复
mcloud local build --var NODE_ENV=production

# 使用本地 .env 文件构建
mcloud local build --env-file .env

# 复用 Docker 缓存以加快重新构建
mcloud local build --docker-cache

技能介绍

用途

主要能力

约束与限制

使用方式：复现一次构建失败

示例