跳到主要内容

全局选项

全局选项适用于所有 CloudBase CLI 命令，在 bin/tcb.js 中通过 program.option() 注册，无需在各命令中重复声明。

选项列表​

环境 ID​

-e, --env-id <envId>

指定云开发环境 ID。

优先级（高到低）：

  1. 命令行参数 --env-id
  2. 配置文件 cloudbaserc.json 中的 envId 字段
  3. 交互式选择（如适用）

示例：

# 部署函数到指定环境
tcb fn deploy app --env-id my-env-123

# 查询环境下的数据库集合
tcb db list --env-id my-env-123
兼容性说明

旧版参数 --envId 已废弃，但仍然可用（在帮助中隐藏）。推荐使用 --env-id。

地域​

-r, --region <region>

指定环境所在地域。支持的地域：ap-shanghai、ap-beijing、ap-guangzhou、ap-singapore。

示例：

# 查询广州地域的环境列表
tcb env list --region ap-guangzhou

# 部署函数到北京地域环境
tcb fn deploy app --region ap-beijing --env-id bj-env-123

多地域错误提示：
当环境不在默认地域（上海）时，CLI 会提示切换地域并自动重试。

JSON 输出​

--json

以 JSON 格式输出结果，便于脚本和 AI 解析。

行为：

  • 抑制所有非 JSON 内容（版本提示、进度条、彩色输出等）
  • 确保 stdout 仅包含可解析的 JSON
  • 错误信息也以 JSON 格式输出：{ "error": { "code": "...", "message": "...", "exit_code": N } }

示例：

# 获取函数列表（JSON 格式）
tcb fn list --json

# 查询环境信息并用 jq 解析
tcb env list --json | jq '.data[0].EnvId'

非交互模式​

-y, --yes

跳过所有确认提示，对所有询问自动选择默认选项（通常为"是"）。

适用场景：

  • CI/CD 流水线
  • 自动化脚本
  • 批量操作

示例：

# 强制删除函数，跳过确认
tcb fn delete app --yes

# 批量部署，不询问
tcb fn deploy --yes

详细输出​

--verbose

打印内部运行信息，包括：

  • 详细的错误栈
  • API 请求参数
  • 中间步骤日志

用途：

  • 调试 CLI 行为
  • 排查意外错误
  • 提交 Bug 报告

示例：

# 调试函数部署失败原因
tcb fn deploy app --verbose

配置文件路径​

--config-file <path>

指定配置文件路径，默认为当前目录下的 cloudbaserc.json。

示例：

# 使用自定义配置文件
tcb fn deploy --config-file ./configs/prod.json

# 使用上级目录的配置
tcb hosting deploy --config-file ../cloudbaserc.json

环境模式​

--mode <mode>

指定加载 .env 文件的环境模式（如 development、production）。

用途：

  • 根据环境加载不同的配置
  • 与前端构建工具（Vite、Next.js 等）配合使用

示例：

# 开发模式部署
tcb app deploy --mode development

# 生产模式部署
tcb app deploy --mode production

组合使用​

全局选项可以自由组合：

# 非交互 + JSON 输出（适合 CI/CD）
tcb fn list --yes --json --env-id my-env

# 详细日志 + 指定地域（排查问题）
tcb fn deploy app --verbose --region ap-guangzhou --env-id gz-env-123

# 自定义配置 + 环境模式（本地开发）
tcb app deploy --config-file ./dev-config.json --mode development

CI/CD 最佳实践​

1. 使用 --json + --yes 确保幂等性​

# GitHub Actions 示例
- name: Deploy function
  run: |
    tcb fn deploy app --env-id ${{ secrets.ENV_ID }} --json --yes

2. 解析 JSON 输出提取信息​

# 提取函数列表中的第一个函数名
FUNC_NAME=$(tcb fn list --json | jq -r '.data[0].FunctionName')
echo "Latest function: $FUNC_NAME"

3. 错误处理​

# 捕获错误码
tcb fn deploy app --json || EXIT_CODE=$?
if [ $EXIT_CODE -ne 0 ]; then
  echo "Deployment failed with exit code $EXIT_CODE"
  exit $EXIT_CODE
fi

常见问题​

Q: --env-id 和 --envId 有什么区别？​

A: 功能完全相同。--envId 是旧版参数，已废弃但仍可用。推荐使用 --env-id（符合 kebab-case 命名规范）。

Q: 如何在 CI/CD 中避免交互式提示？​

A: 使用 --yes 参数跳过所有确认提示：

tcb fn delete old-func --yes

Q: --json 输出的错误格式是什么？​

A: 错误信息以 JSON 格式输出：

{
  "error": {
    "code": "FUNCTION_NOT_FOUND",
    "message": "函数 app 不存在",
    "exit_code": 4
  }
}

Q: 如何指定多个全局选项？​

A: 全局选项的顺序无关紧要，可以任意组合：

tcb fn deploy app --json --yes --verbose --env-id my-env --region ap-guangzhou

参考资料​