# @cloudbase/cli 中文文档

规范地址：https://npmcn.com/package/%40cloudbase/cli/

版本：3\.9\.2
npm 元数据更新时间：2026-11-09T07:30:17.098Z
中文译文更新时间：2026-11-10T02:36:06.498Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cloudbase/cli
原文对照：https://npmcn.com/package/%40cloudbase/cli/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：29.8 MB，12 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2019-03-02T09:21:52.579Z
- 最新版本发布：2026-11-09T07:30:16.084Z
- 近 30 天下载量：61510（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：647（近 12 个月 148 个）

## 中文简介

Tencent CloudBase (独立捆绑) 的 CLI

## 安装

```sh
npm install @cloudbase/cli
```

也可以使用：`pnpm add @cloudbase/cli`、`yarn add @cloudbase/cli`、`bun add @cloudbase/cli`

## README

# CloudBase 命令行工具 ![npm (tag)](https://img.shields.io/npm/v/@cloudbase/cli)

CloudBase CLI 是一个开源的命令行界面交互工具，用于帮助用户快速、方便的部署项目，管理云开发资源。

## 主要功能

-   **云开发资源管理**：快速部署项目，管理云函数、数据库、存储等资源
-   **AI 开发助手**：集成多种 AI 工具（Claude、Qwen、Codex、Aider 等），提升开发效率
-   **MCP 协议支持**：内置 `cloudbase-mcp` 命令，支持 Model Context Protocol，无需额外安装
-   **模板下载**：提供多种项目模板，自动配置 IDE 和 MCP 环境

## 安装 CloudBase CLI

### npm

```shell
npm install -g @cloudbase/cli
```

### yarn

```shell
yarn global add @cloudbase/cli
```

安装完成后，你可以使用 `cloudbase -v` 验证是否安装成功，如果输出了类似下面的版本号，则表明 CloudBase CLI 被成功安装到您的计算机中。

```text
2.7.8
```

## 可用命令

-   `cloudbase` 或 `tcb`：主要的 CLI 命令
-   `cloudbase-mcp`：内置的 MCP 服务器命令，支持 Model Context Protocol

## CloudBase CLI 运行要求

**Node.js 8.6.0+**

## 文档

请访问[教程与文档](https://docs.cloudbase.net/cli/intro.html)了解详细的使用方法。

## 退出码说明

CloudBase CLI 使用结构化退出码帮助 CI/CD 流水线和 AI Agent 精确处理错误：

| 退出码 | 含义 | 典型场景 | 应对策略 |
| --- | --- | --- | --- |
| 0 | 成功 | 命令正常执行 | \- |
| 1 | 通用错误 | 未分类的异常 | 查看错误信息，手动排查 |
| 2 | 认证失败 | 未登录、token 过期、无权限 | 执行 `tcb login` 重新登录 |
| 3 | 参数错误 | 缺少必填参数、格式非法、枚举值错误 | 检查命令参数，参考 `tcb <cmd> --help` |
| 4 | 资源不存在 | 环境 ID/函数名无效、集合不存在 | 确认资源名称，用 `tcb env list` / `tcb fn list` 验证 |
| 5 | 云 API 错误 | CloudBase API 返回错误、网络超时 | 检查网络连接，查看 API 错误详情，必要时重试 |
| 6 | 本地文件错误 | cloudbaserc.json 缺失/损坏、路径不存在 | 检查配置文件，用 `tcb init` 重新初始化 |

**CI/CD 脚本示例**：

```bash
# 根据退出码自动重试
tcb fn deploy || {
  code=$?
  case $code in
    2) echo "Auth failed, retrying..." && tcb login && tcb fn deploy ;;
    5) echo "API error, retrying in 30s..." && sleep 30 && tcb fn deploy ;;
    *) echo "Unrecoverable error (code $code)" && exit $code ;;
  esac
}
```

完整定义参见：[src/exit-codes.ts](https://npmcn.com/package/%40cloudbase/cli/src/exit-codes.ts)

## 意见反馈

您可以到 GitHub Repo 新建一个 [issue](https://github.com/TencentCloudBase/cloudbase-cli/issues) 反馈您在使用过程中遇到的问题或建议。

## 常见问题

### @cloudbase/cli 是什么？

Tencent CloudBase \(独立捆绑\) 的 CLI

### 如何安装 @cloudbase/cli？

在项目目录运行 npm install @cloudbase/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 tcb、cloudbase、cloudbase-mcp，可以用 npx tcb 直接运行。

### @cloudbase/cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cloudbase\_\_cli 是否存在。

### @cloudbase/cli 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @cloudbase/cli 可以商用吗？

@cloudbase/cli 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cloudbase/cli 的下载量有多少？

根据 npm 官方下载统计，@cloudbase/cli 在 2026/10/10 – 2026/11/08 这 30 天内被下载 61,510 次，日均约 2,050 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cloudbase/cli 还在维护吗？

最新版本 3\.9\.2 发布于 2026/11/09（今天）；至今共发布 647 个版本，其中过去 12 个月发布了 148 个；首次发布于 2019/03/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。