# @cloudbase/toolbox 中文文档

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

版本：0\.9\.4
npm 元数据更新时间：2026-11-09T03:28:53.105Z
中文译文更新时间：2026-11-10T02:38:25.018Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：4.2 MB，201 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：26 个
- 首次发布：2020-04-16T09:31:45.267Z
- 最新版本发布：2026-11-09T03:28:52.929Z
- 近 30 天下载量：16893（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：119（近 12 个月 33 个）

## 中文简介

云库工具箱

## 安装

```sh
npm install @cloudbase/toolbox
```

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

## README

# Cloudbase Toolbox

云开发 Node Toolbox，工具合集，仅支持 Node 8.9+ 以上版本。

> **兼容性约定**：本包只保证在**未经降级编译**的环境下使用（我们自己的消费方 `cloudbase-cli` / `@cloudbase/cloudbase-mcp` / `@cloudbase/manager-node` 均为 `target: node`，不会把依赖降级到 ES5）。若你把它降级编译到 ES5，`class X extends Error` 会丢失原型链（`toJSON()` 等原型成员消失、`instanceof` 失效）—— 判断错误请改用结构判据 `isCloudBaseError()`。

## V2 配置解析器

`@cloudbase/toolbox` **0.4.0**版本起，支持了新的 `cloudbaserc` 配置文件解析器。

当前配置文件无法满足现阶段的需求（重写配置文件，环境变量支持等），需要对配置文件进行重新设计。

新版配置文件 `version` 为 `2.0`，只支持 `JSON` 格式的配置文件，只有 `version` 声明为 `2.0` 的配置文件才支持模板变量。

### 使用方法

你可以在 `cloudbaserc.json` 配置文件中使用变量，从环境变量或其他数据源获取动态的数据。使用 `{{}}` 包围的值定义为变量，引用了数据源中的值。

```json
{
  "envId": "envId",
  "functionRoot": "./functions",
  "functions": [
      {
        "name": "{{variable}}"
      }
  ]
}
```

#### 数据源

CloudBase 定义多个数据源的命名空间，用于区分不同的数据源。你可以通过 `命名空间.变量名` 引用数据，如 `{{tcb.envId}}`

| 命名空间 | 变量名 | 含义 |
| --- | --- | --- |
| tcb | envId | 配置文件或通过命令行参数指定的环境 Id |
| util | uid | 24 位的随机字符串 |
| env | \* | 从 `.env` 文件中加载的环境变量 |

#### env 环境变量

CloudBase 支持了 `env` 数据源，可以加载 [`.env`](https://github.com/motdotla/dotenv) 文件中的环境变量，并在使用 CLI 时，通过 `--mode` 参数指定不同的环境。

你可以替换你的项目根目录中的下列文件来指定环境变量：

```
.env                # 在所有的环境中被载入
.env.local          # 在所有的环境中被载入，可以加入 .gitignore 忽略
.env.[mode]         # 只在指定的模式中被载入
```

在加载 env 文件时，`.env` 和 `.env.local` 会被直接加载，当指定 `--mode [mode]` 时，会再加载 `.env.[mode]` 文件，并遵循如下的合并顺序：`.env.[mode] > .env.local > .env`，即 `.env.[mode]` 中的同名变量会覆盖 `.env.local` 和 `.env` 文件中的同名变量，以此类推。

如使用 `tcb framework:deploy --mode test` 命令时，会自动加载 `.env`，`.env.local` 以及 `.env.test` 等三个文件中的环境变量合并使用。

如 `.env` 文件中存在以下变量

```jsx
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=s1mpl3
```

则可以在配置文件中使用

```json
{
  "envId": "xxx",
  "functionRoot": "./functions",
  "functions": [
      {
          "name": "test",
          "envVariables": {
              "PASSWORD": "{{env.DB_PASSWORD}}"
          }
      }
  ]
}
```

### 支持字段

#### version

当期配置文件版本，新版本从 `2.0` 开始，没有 `version` 字段的配置文件视为 `1.0` 版本。

#### envId

环境 Id

#### functionRoot

存放函数的根文件夹

#### functions

云函数配置

#### engine

保留字段

### 使用解析器

使用方法如下：

```js
import { ConfigParser } from '@cloudbase/toolbox'

const configParser = new ConfigParser({
    // 当前工作目录，搜索配置文件，.env 文件，默认为 process.cwd
    cwd: '',
    // 写本地配置时，遇到相同 key 时的处理策略
    cover: false,
    // 直接指定配置文件的路径，否则在 cwd 目录下尝试查找配置文件
    configPath: ''
})

// 获取全部配置文件
await configParser.get()
// 获取 envId
await configParser.get('envId')
// 获取第一个函数的超时时间，如果不存在，则返回默认值 3
await configParser.get('functions[0].timeout', 3)

await configParser.update('functions[0].timeout', 5)
```

直接使用静态方法

```js
import { ConfigParser } from '@cloudbase/toolbox'

// 获取全部配置文件
await ConfigParser.get()
// 获取 envId
await ConfigParser.get('envId')
// 获取第一个函数的超时时间，如果不存在，则返回默认值 3
await ConfigParser.get('functions[0].timeout', 3)
```

## 常见问题

### @cloudbase/toolbox 是什么？

云库工具箱

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

在项目目录运行 npm install @cloudbase/toolbox，或使用 pnpm add / yarn add / bun add。

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

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

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

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

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

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

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

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

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

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