mcpField
M
mcloud-local

mcloud-local

github.com/medusajs云与 DevOps234831 次安装1 周前更新
代码仓库

关于 mcloud-local

mcloud-local 指导使用 mcloud CLI 在本机重现 Cloud 后端或 storefront 构建失败，无需先触发新的 Cloud 构建。

主要功能

  1. 01在本机运行后端或 storefront 构建
  2. 02使用 Cloud 项目和环境设置
  3. 03覆盖变量或读取本地 .env 文件
  4. 04可选启用 Docker 构建缓存
  5. 05通过退出码判断构建结果

适用场景

  1. 01推送更改前调试部署构建失败
  2. 02在本机测试构建变量更改
  3. 03重现 storefront 构建失败

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/medusajs/medusa-agent-skills --skill mcloud-local

安装后在 Claude Code 中输入/mcloud-local确认已加载。

详细介绍

Cloud CLI：本地命令

执行 mcloud local build，在本地运行 Cloud 构建，模拟 Cloud 构建项目的方式。可用它调试 build-failed 部署，无需推送更改并等待完整的 Cloud 构建。

限制

  • 不支持 --json 标志。 local build 会以纯文本形式流式输出构建日志，并通过其退出代码指示结果（0 = 成功）。请勿将其输出解析为 JSON。
  • 需要安装并运行 Docker，且必须在项目的 Git 仓库内运行。
  • 仅复现 build-failed（构建）故障，不复现 deployment-failed（运行时）故障。对于运行时故障，请使用 mcloud logs --deployment <id>。
  • mcloud CLI v0.1.10 起提供。
  • 默认禁用 Docker 构建缓存，因此变量更改始终会使缓存失效；传入 --docker-cache 可启用缓存。

命令

local build

在本地运行 Cloud 构建。根据已关联的 Cloud 项目和环境推断根路径与构建变量。默认构建后端；传入 --type storefront 可构建 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 或句柄（回退到当前活动上下文）
  • -e/--environment <handle> — 使用其变量的环境（回退到当前活动上下文）
  • -t/--type <backend|storefront> — 构建类型（默认：backend）
  • --root-path <path> — 相对于仓库根目录的后端根路径（若省略则自动推断；若未找到 Cloud 项目则为 .）
  • --storefront-path <path> — 相对于仓库根目录的 storefront 路径，适用于 --type storefront（若省略则自动推断）
  • --env-file <path> — 使用本地 .env 文件，而非 Cloud 环境的变量
  • -v/--var <KEY=VALUE> — 覆盖单个构建变量；可重复使用
  • --docker-cache — 启用 Docker 构建缓存（默认：false）

输出：

  • 成功时（退出代码为 0），后端镜像会标记为 <repository-name>:cloud-local-build-<commit-hash>；storefront 构建会写入其输出目录并打印路径。
  • 失败时（退出代码非零），命令会因失败步骤的错误而退出——请像调试 Cloud 构建那样进行调试。

复现构建故障

检出失败部署所构建的同一提交，使本地构建与之匹配，然后根据退出代码进行处理：

# Identify the failing deployment and the commit it built
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 构建。

示例

# Reproduce the backend build for the active context
mcloud local build

# Reproduce the storefront build
mcloud local build --type storefront --storefront-path apps/storefront

# Test a build-variable fix without editing code
mcloud local build --var NODE_ENV=production

# Build against a local .env file
mcloud local build --env-file .env

# Reuse the Docker cache for a faster rebuild
mcloud local build --docker-cache

评论

支持 Markdown