# @cloudbase/cloud-api 中文文档

规范地址：https://npmcn.com/package/%40cloudbase/cloud-api/

版本：0\.5\.5
npm 元数据更新时间：2026-09-09T07:53:27.584Z
中文译文更新时间：2026-11-10T02:36:06.853Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：56.3 kB，26 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2020-03-27T02:01:29.892Z
- 最新版本发布：2022-06-22T08:23:30.140Z
- 近 30 天下载量：16044（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 0 个）

## 中文简介

云阿庇请求包.

## 安装

```sh
npm install @cloudbase/cloud-api
```

也可以使用：`pnpm add @cloudbase/cloud-api`、`yarn add @cloudbase/cloud-api`、`bun add @cloudbase/cloud-api`

## README

# @cloudbase/cloud-api

云 API 3.0 请求封装，仅适用于 Node。

## 调用云API

支持 API 秘钥或临时秘钥鉴权。

```ts
import { CloudApiService } from '@cloudbase/cloud-api'

const service = new CloudApiService({
    service: 'tcb',
    credential: {
        secretId: 'xxx',
        secretKey: 'xxx',
        token: 'xxx'
    }
})

service.request('DescribeEnvs').then(console.log)
// 或
service
    .request({
        action: DescribeEnvs
    })
    .then(console.log)
```

或

```js
const { CloudApiService } = require('@cloudbase/cloud-api')

const service = new CloudApiService({
    service: 'tcb',
    credential: {
        secretId: 'xxx',
        secretKey: 'xxx'
    }
})

service.request('DescribeEnvs').then(console.log)
```

结果

```ts
{
  EnvList: [],
  RequestId: '09a1ece6-7cb1-4a8f-b8b6-e4cc066d1fbe'
}
```

## 异步 credential

在某些情况下，你的 credential 可能是异步获取。你可以配置 `getCredential` 方法，异步传递 credential 信息。建议结合 `getInstance()` 方法使用，避免重复请求获取 credential 信息。

```ts
const tcbService = CloudApiService.getInstance({
    service: 'tcb',
    getCredential: async () => {
        // 你的异步逻辑
        return new Promise((resolve) => {
            setTimeout(() => {
                resolve({})
            }, 1000)
        })
    }
})

const res = await tcbService.request('DescribeEnvs')
```

## request()

定义：`async request(action: string, data: Record<string, any> = {}, method: 'POST' | 'GET' = 'POST')`

使用 request 方法发起请求。

## getInstance()

`getInstance()` 静态方法内部是一个工厂函数，会根据服务类型缓存实例，能有效避免重复初始化实例带来的开销

```ts
const tcbService = CloudApiService.getInstance({
    credential,
    service: 'tcb'
})

const res = await tcbService.request('DescribeEnvs', {
    empty: null,
    b: undefined
})
```

## 清除内存中的 credential 缓存

在某些特殊的情况下，你可能需要在不退出进程的情况下重载 `credential`。你可以使用 `clearCredentialCache()` 方法清除内存中的 `credential` 缓存，使得下次请求前通过 `getCredential` 函数重新获取 `credential`

```ts
const tcbService = new CloudApiService({
    service: 'tcb',
    getCredential: () => {
        return new Promise((resolve) => {
            setTimeout(() => {
                resolve(credential)
            }, 1000)
        })
    }
})

const res = await tcbService.request('DescribeEnvs')

tcbService.clearCredentialCache()

// 重新加载 credential
const res = await tcbService.request('DescribeEnvs')
```

### 选项

下面是 TS 定义

```ts
interface ServiceOptions {
    // 服务名，如 tcb scf
    service: string
    // 服务版本，如 2018-06-14
    version?: string
    // http 请求代理，如 http://127.0.0.1:1235
    // 需要准确声明，本 SDK 不会自动解析 proxy
    proxy?: string
    // 超时时间，毫秒
    timeout?: number
    // 基本参数，会被拼接到请求参数中
    baseParams?: Record<string, any>
    // 身份信息
    credential?: Credential
    // 获取身份信息的函数
    getCredential?: () => Promise<Credential> | Credential
}

interface Credential {
    secretId: string
    secretKey: string
    token?: string
}
```

## 调用weda后端

```ts
import { wedaRequest } from '@cloudbase/cloud-api'

// 使用示例
wedaRequest({
  action: 'DescribeWedaUserId',
  credentials: {
    secretId: 'xxx',
    secretKey: 'xxxx',
    sessionToken: 'xxxxxx',
  },
  /** 环境ID */
  envId: 'xxx-xxxx',
  /**
   * 调用的weda环境类型
   *  预览-pre，正式-prod
   */
  envType: 'pre',
  /** 用户ID */
  uid: 'xxxxxx',
  /** 
   * uid 类型, 1.tcb 2.微信 3.企业微信 4.weda内部
   */
  source: 1
}).then(res => console.log(res))

// 方法定义, 返回原云API Response 内容
wedaRequest(params: IWedaRequestParams, config?: Partial<IWedaConfig>): Promise<any>

/**
 * 请求参数
 */
export interface IWedaRequestParams {
  /** 请求方法 */
  action: string;
  /**
   * 认证信息
   *  在tcb云函数中可通过 tcb.getCloudbaseContext 返回的环境变量获取相关信息:
   *    TENCENTCLOUD_SECRETID
   *    TENCENTCLOUD_SECRETKEY
   *    TENCENTCLOUD_SESSIONTOKEN
   */
  credentials: ICredentials | (() => Promise<ICredentials>)
  /**
   * 环境ID
   *    在tcb云函数中可通过 tcb.getCloudbaseContext(context) 返回的环境变量 TCB_ENV 获取
   */
  envId: string;
  /**
   * 客户端IP地址, 方便后端进行统计, 无可不传
   *  在tcb云函数中可通过 tcb.getCloudbaseContext 返回的 WX_CLIENTIP(微信侧) TCB_SOURCE_IP(云开发侧)拿到客户端IP地址
   *  详细文档 https://docs.cloudbase.net/api-reference/server/node-sdk/env.html#getcloudbasecontext
   */
  clientIp?: string
  /**
   * 自定义请求ID, 方便前后端调试, 无可不传
   *  在tcb 云函数中, 若可以保证前端一次云函数调用, 只向weda后端发起一次请求, 这可以通过 tcb.parseContext 拿到云函数的请求 request_id 并复用该ID
   *    若不能保证上述条件, 则不要复用云函数请求ID, 否则导致请求链路出问题难以定位
   *  详细文档 https://docs.cloudbase.net/api-reference/server/node-sdk/env.html#parsecontext
   */
  requestId?: string
  /**
   * 调用的weda环境类型
   *  预览-pre，正式-prod
   */
  envType: 'pre' | 'prod'
  /**
   * 用户ID
   *    在tcb 云函数中获取 uid/uidSource 的方法可参考下边的函数 getUserSource
   */
  uid: string;
  /** 
   * uid 类型, 1.tcb 2.微信 3.企业微信 4.weda内部
   */
  source: 1 | 2 | 3 | 4
  /**
   * 方法的其他参数
   */
  data?: Record<string, any>
}

interface IWedaConfig {
  /** 请求的接口地址, 默认 'https://gateway.weda.tencent-cloud.com/wedaapi' */
  url: string
  /**
   * 请求目标, 与 url 意义类似, 但可通过设置为 prod/pre 来指定地址, 优先使用 target
   * 可以是下边三个值
   *  'prod' 正式地址
   *  'pre' 预发地址
   *  'demo' 体验地址 
   *  url 任意一个url
   */
  target?: string
  /** 请求方法, 默认 POST */
  method: string
  /** 额外的自定义头 */
  headers?: Record<string, any>
  /** 自定义http代理地址 */
  proxy?: string
}

interface ICredentials {
  secretId: string
  secretKey: string
  sessionToken: string
}

```

在tcb云函数中获取uid及uidSource

```ts
/** 获取用户来源信息 */
export function getUserSource(context) {
  //  context 为tcb云函数的入口函数接收的 context, 必须传递该参数, 否则解析不到用户ID相关信息
  const envInfo = tcb.getCloudbaseContext(context);
  // @ts-ignore
  const openId: string | undefined = envInfo.WX_FROM_OPENID || envInfo.WX_OPENID;
  const uid = envInfo.TCB_UUID;
  if (!openId && !uid) {
    return;
  }
  return {
    /** uid 类型
     * 1.tcb 2.微信 3.企业微信 4.weda内部
     */
    source: openId ? 2 : 1,
    uid: openId || uid,
  };
}
```

### 调试

调试时, 可以通过在环境变量中增加 `NODE_DEBUG=weda-request` 来打印出详细的冗余日志

## 常见问题

### @cloudbase/cloud-api 是什么？

云阿庇请求包\.

### 如何安装 @cloudbase/cloud-api？

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

### @cloudbase/cloud-api 支持 TypeScript 吗？

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

### @cloudbase/cloud-api 支持 ESM 还是 CommonJS？

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

### @cloudbase/cloud-api 可以商用吗？

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

### @cloudbase/cloud-api 的下载量有多少？

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

### @cloudbase/cloud-api 还在维护吗？

最新版本 0\.5\.5 发布于 2022/06/22（4 年前）；至今共发布 41 个版本，其中过去 12 个月发布了 0 个；首次发布于 2020/03/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。