mcloud-local

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloud CLI: Local Command

Cloud CLI：本地命令

Execute

mcloud local build

to run a Cloud build on the local machine, mirroring how Cloud builds the project. Use it to debug

build-failed

deployments without pushing changes and waiting for a full Cloud build.

执行

mcloud local build

在本地机器上运行Cloud构建，复刻Cloud构建项目的方式。无需推送变更并等待完整的Cloud构建，即可用它来调试标记为

build-failed

的部署问题。

Constraints

限制条件

No
--json
flag.
```
local build
```
streams plaintext build output and signals the result through its exit code (
```
0
```
= success). Do not parse its output as JSON.
Requires Docker installed and running, and must run from inside the project's Git repository.
Reproduces
```
build-failed
```
(build) failures only — not
```
deployment-failed
```
(runtime) failures. For runtime failures, use
```
mcloud logs --deployment <id>
```
.
Available since mcloud CLI v0.1.10.
The Docker build cache is disabled by default so variable changes always invalidate the cache; pass
```
--docker-cache
```
to enable it.

不支持
--json
参数。
```
local build
```
会输出纯文本构建日志，并通过退出码（
```
0
```
表示成功）标识结果。请勿将其输出解析为JSON格式。
需要安装并运行Docker，且必须在项目的Git仓库内执行命令。
仅能重现
```
build-failed
```
（构建阶段）的失败，无法重现
```
deployment-failed
```
（运行阶段）的失败。针对运行阶段失败，请使用
```
mcloud logs --deployment <id>
```
命令。
从mcloud CLI v0.1.10版本开始提供此功能。
Docker构建缓存默认处于禁用状态，因此变量变更总会使缓存失效；可传入
```
--docker-cache
```
参数启用缓存。

Command

命令

local build

Run a Cloud build locally. Infers the root path and build variables from the linked Cloud project and environment. Builds the backend by default; pass

--type storefront

for the storefront.

bash

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

Options:

```
-o/--organization <id>
```
— Organization ID (falls back to active context)
```
-p/--project <id-or-handle>
```
— Project ID or handle (falls back to active context)
```
-e/--environment <handle>
```
— Environment whose variables are used (falls back to active context)
```
-t/--type <backend|storefront>
```
— Build type (default:
```
backend
```
)
```
--root-path <path>
```
— Backend root path relative to the repo root (inferred if omitted;
```
.
```
if no Cloud project found)
```
--storefront-path <path>
```
— Storefront path relative to the repo root, for
```
--type storefront
```
(inferred if omitted)
```
--env-file <path>
```
— Use a local
```
.env
```
file instead of the Cloud environment's variables
```
-v/--var <KEY=VALUE>
```
— Override a single build variable; repeatable
```
--docker-cache
```
— Enable the Docker build cache (default:
```
false
```
)

Output:

On success (exit
```
0
```
), the backend image is tagged
```
<repository-name>:cloud-local-build-<commit-hash>
```
; a storefront build writes its output directory and prints the path.
On failure (non-zero exit), the command exits with the failing step's error — debug it as you would a Cloud build.

在本地运行Cloud构建。从关联的Cloud项目和环境中自动推断根路径和构建变量。默认构建后端；若需构建前端商城，传入

--type storefront

参数。

bash

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>
```
—— 相对于仓库根目录的前端商城路径，仅当使用
```
--type storefront
```
时生效（若省略则自动推断）
```
--env-file <path>
```
—— 使用本地
```
.env
```
文件替代Cloud环境的变量
```
-v/--var <KEY=VALUE>
```
—— 覆盖单个构建变量；可重复使用该参数
```
--docker-cache
```
—— 启用Docker构建缓存（默认值：
```
false
```
）

输出：

成功时（退出码
```
0
```
），后端镜像会被标记为
```
<repository-name>:cloud-local-build-<commit-hash>
```
；前端商城构建会生成输出目录并打印其路径。
失败时（非零退出码），命令会伴随失败步骤的错误退出；可像调试Cloud构建一样排查问题。

Reproduce a Build Failure

重现构建失败场景

Check out the same commit the failed deployment built so the local build matches, then route on the exit code:

bash

undefined

检出失败部署所基于的提交版本，确保本地构建与云端一致，然后根据退出码进行排查：

bash

undefined

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


Once the local build exits `0`, push the fix to the tracked branch and start a fresh Cloud build with `mcloud environments trigger-build <env>`.

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 "本地构建成功；此提交版本无法重现失败场景。" else echo "本地构建失败；查看输出日志定位失败步骤。" fi


当本地构建退出码为`0`后，将修复内容推送到跟踪分支，并使用`mcloud environments trigger-build <env>`启动全新的Cloud构建。

Examples

示例

bash

undefined

bash

undefined

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

基于本地.env文件进行构建

mcloud local build --env-file .env

Reuse the Docker cache for a faster rebuild

复用Docker缓存以加快重建速度

mcloud local build --docker-cache

undefined

mcloud local build --docker-cache

undefined