跳到主要内容

全局选项

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

选项列表​

帮助信息​

-h, --help

查看当前命令的帮助信息。

v3 版本的 --help 输出相比旧版更完整，也更适合作为命令发现入口。实际使用时，通常可以按“顶层命令 → 子命令 → 具体动作”的路径逐级下钻，快速确认真实可用的命令结构。

从输出结构上看，新版帮助信息通常会同时覆盖几类关键信息：

  • 用法（Usage）
  • 参数说明（Options）
  • 示例（Examples）
  • 相关命令（Related Commands）
  • 对应文档链接（Docs）

这意味着 --help 不再只是“参数速查”，而更接近命令的自解释说明。它的价值不只在于信息更多，而在于输出顺序本身已经带有引导性：先告诉您命令怎么写，再告诉您关键参数怎么选，接着补充示例、相关命令和文档，减少在帮助、文档、搜索结果之间来回切换。对于以下场景尤其有价值：

  • 首次使用某个命令时快速确认正确语法
  • 在终端里直接查示例，减少来回翻文档
  • 在脚本或 CI 编写前先确认参数签名
  • 让 AI 在生成命令前先读取真实帮助信息，降低命令幻觉

示例：

# 先看顶层命令结构
tcb --help

# 再下钻到具体子命令
tcb fn deploy --help

# 最后查看具体动作的参数和示例
tcb logs search --help

例如 tcb fn deploy --help 这类输出，会把命令写法、关键参数、示例、相关命令和文档链接放在一起。开发者可以直接确认“这条命令怎么写”，AI 也可以先读帮助再生成命令，减少猜命令和试错。

$ tcb fn deploy --help
Usage: tcb fn deploy [options] [name]

Options:
  --force
  --dir <dir>
  --runtime <runtime>
  --json

示例:
  tcb fn deploy hello
  tcb fn deploy hello --force
  tcb fn deploy --all

相关命令:
  tcb fn invoke
  tcb fn log

文档:
  https://docs.cloudbase.net/cli-v1/functions/deploy
AI 协作建议

如果您会让大模型帮您生成 tcb 命令，建议先执行一次对应命令的 --help，或者配合 tcb docs 一起使用。相比仅依赖模型记忆，读取实时帮助信息更可靠。

环境 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

参考资料​