# @clevercloud/client 中文文档

规范地址：https://npmcn.com/package/%40clevercloud/client/

版本：12\.6\.11
npm 元数据更新时间：2026-11-06T14:39:52.735Z
中文译文更新时间：2026-11-10T01:17:10.251Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40clevercloud/client
原文对照：https://npmcn.com/package/%40clevercloud/client/?lang=original
项目主页：https://github.com/CleverCloud/clever-client.js
源码仓库：https://github.com/CleverCloud/clever-client.js

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

- 包体积（解压后）：4.5 MB，3083 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：2 个
- peer 依赖：linkedom ^0\.18\.13，eventsource ^4\.0\.0
- 首次发布：2019-07-22T17:07:19.939Z
- 最新版本发布：2026-11-06T14:39:52.304Z
- 近 30 天下载量：42828（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：97（近 12 个月 25 个）

## 中文简介

JavaScript REST 客户端和用于智能云 API的 utils

## 安装

```sh
npm install @clevercloud/client
```

也可以使用：`pnpm add @clevercloud/client`、`yarn add @clevercloud/client`、`bun add @clevercloud/client`

## README

# JavaScript REST 客户端和用于智能云 API的 utils

> 🚧 **新客户端文档可用**:关于新的命令模式客户端(β),参见 [新城区 (MD)](https://npmcn.com/package/%40clevercloud/client/NEW_CLIENT.md)

## 这是什么?

这个项目包含一个RIST客户端,用于Clever Cloud的API和一些utils.

## 我怎么用这个?

首先,需要安装Node.js模块:

```sh
pnpm install @clevercloud/client
```

我们建议使用 [爱](https://mise.jdx.dev/) 以确保您依赖与我们相同的节点.js & pnpm 版本(定义于 [`mise.toml`](https://npmcn.com/package/%40clevercloud/client/mise.toml)) (中文(简体) ).

所有API REST路径都可以作为"服务"中组织的"功能"访问. 一个服务功能的调用将只是准备 HTTP 请求,并通过承诺返回对象中的请求参数. 它不会认证请求,也不会发送.

您需要链接一些助手到函数调用:

-   指定 API 主机( prod, preprod...)
-   添加正确的认证头( oAuth v1 或其他...)
-   用您最喜欢的 lib/ code 发送 HTTP 请求
-   用您最喜欢的 lib/ code 处理响应

这些帮助者已准备好用于浏览器或节点.js和oAuth v1签名认证. 推荐的方法是把这些帮助者包裹在您的应用程序的一个位置,并在需要发送API呼叫的地方重新使用.

以下是使用带有 oAuth v1 签名的 ECMAScript 模块并使用 `fetch` API 发送请求 .

在文件中,显示此函数 :

```js
import { addOauthHeader } from '@clevercloud/client/esm/oauth.js';
import { prefixUrl } from '@clevercloud/client/esm/prefix-url.js';
import { request } from '@clevercloud/client/esm/request.fetch.js';

export function sendToApi (requestParams) {

  // load and cache config and tokens
  const API_HOST = 'https://api.clever-cloud.com'
  const tokens = {
    OAUTH_CONSUMER_KEY: 'your OAUTH_CONSUMER_KEY',
    OAUTH_CONSUMER_SECRET: 'your OAUTH_CONSUMER_SECRET',
    API_OAUTH_TOKEN: 'your API_OAUTH_TOKEN',
    API_OAUTH_TOKEN_SECRET: 'your API_OAUTH_TOKEN_SECRET',
  }

  return Promise.resolve(requestParams)
    .then(prefixUrl(API_HOST))
    .then(addOauthHeader(tokens))
    .then(request);
    // chain a .catch() call here if you need to handle some errors or maybe redirect to login
}
```

注:如果您的工程依赖于特定的 REST 库( xios, jQuery...) , 您必须写出自己的请求功能, 将参数插入到您的 lib 中, 而不是使用 `request.fetch.js`。 。 。 .

然后,在您的应用程序的任何文件中,直接导入您需要的 API 函数( 它有助于树摇动), 调用它并添加一个 `.then(sendToApi)` 像这样:

```js
import { getAllEnvVars } from '@clevercloud/client/esm/api/v2/application.js';
import { sendToApi } from '../send-to-api.js';

const envVars = await getAllEnvVars({ id: oid, appId }).then(sendToApi);
```

注意: 它返回承诺, 您可能想要使用 `await` 带着它.

## 我怎么才能得到OAuth配置?

建议在下列日期编写一般性文件: [我们的网站](https://www.clever.cloud/developers/api/howto#oauth1)。 。 。 . 如文件所指出:

> 你需要在聪明的云层控制台上创建一个OAuth消费者代币. 点击"创造...",然后点击组织名称下的"Oauth消费者". 所有创建的消费者都将出现在应用程序和附加物的列表下.

一旦你得到消费者,你仍然需要生成 AAuth 代币。 你可以在浏览器里跳整个Auth舞.

如果你使用 [聪明的工具](https://github.com/CleverCloud/clever-tools) CLI,您也可以使用以下命令生成符号 :

```sh
clever login
```

一旦成功登入,您将获得一个标志/秘密夫妇.

## 日志流和事件 API 流 (v2)

### 从智能云获取日志

此流以 SSE 内源曝光 [`component-emitter`](https://www.npmjs.com/package/component-emitter)一个很小的lib 执行一个API 紧密匹配两个 [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) 从DOM和 [`EventEmitter`](https://nodejs.org/api/events.html) 从Node.js.

这里有一个如何使用的例子 `LogsStream` 从应用程序取回活日志 :

```js
// Browser implementation or Node.js implementation
import { LogsStream } from '@clevercloud/client/esm/streams/logs.browser.js';
// import { LogsStream } from '@clevercloud/client/esm/streams/logs.node.js';

// Load and cache config and tokens
const API_HOST = 'https://api.clever-cloud.com';
const tokens = {
  OAUTH_CONSUMER_KEY: 'your OAUTH_CONSUMER_KEY',
  OAUTH_CONSUMER_SECRET: 'your OAUTH_CONSUMER_SECRET',
  API_OAUTH_TOKEN: 'your API_OAUTH_TOKEN',
  API_OAUTH_TOKEN_SECRET: 'your API_OAUTH_TOKEN_SECRET',
};

// Create a LogsStream instance (filter and deploymentId are optional)
const logsStream = new LogsStream({ apiHost: API_HOST, tokens, appId, filter, deploymentId });

// Listen to "log" events
logsStream.on('log', (rawLogLine) => console.log(rawLogLine));

// Open the stream
logsStream.open();
```

### 从智能云获取事件

此流以 WebSocket 内源 曝光 [`component-emitter`](https://www.npmjs.com/package/component-emitter)一个很小的lib 执行一个API 紧密匹配两个 [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) 从DOM和 [`EventEmitter`](https://nodejs.org/api/events.html) 从Node.js.

这里有一个如何使用的例子 `EventsStream` 从智能云平台检索事件:

```js
// Browser and Node.js 21+ implementation
import { EventsStream } from '@clevercloud/client/esm/streams/events.js';

// Load and cache config and tokens
const API_HOST = 'https://api.clever-cloud.com';
const tokens = {
  OAUTH_CONSUMER_KEY: 'your OAUTH_CONSUMER_KEY',
  OAUTH_CONSUMER_SECRET: 'your OAUTH_CONSUMER_SECRET',
  API_OAUTH_TOKEN: 'your API_OAUTH_TOKEN',
  API_OAUTH_TOKEN_SECRET: 'your API_OAUTH_TOKEN_SECRET',
};

// Create an EventsStream instance (appId is optional)
const eventsStream = new EventsStream({ apiHost: API_HOST, tokens, appId });

// Listen to "event" events
eventsStream.on('event', (rawEvent) => console.log(rawEvent));

// Open the stream
eventsStream.open();
```

### 处理错误

当源流发生出错( 网络失败, 认证错误...) 时, 出错事件 :

```js
stream.on('error', (error) => console.error(error));
```

-   默认情况下,当检测出网络故障时,会出错并自动关闭流.
-   如果启用自动重试行为,当检测到网络故障时,不会出错.
-   如果您启用自动重试行为并设置最大次数的重试, 它会释放出错误 .

详见"自动重试行为"部分. .

### 关闭溪流

你可以随时关闭溪流 这样:

```js
stream.close();
```

它不会将事件听众从流实例中移除,这样你就可以轻松地重新打开.

### 自动重试行为

当你打电话 `.open()` 在溪流上,它无法抵御默认的网络故障. 我们有一个选入的自动重试行为 来处理这些, 你可以启用它 当你打开溪流 这样:

```js
stream.open({ autoRetry: true });
```

使用乒乓球系统检测出网络故障. 当检测出这种故障并启用自动重试行为时,源流会被关闭并自动尝试一个新的开口.

你可能不需要,但你可以听与这种自动重试行为相关的事件:

```js
// "close" event is emitted each time a network failure is detected (or any unknown error not related to authentication)
stream.on('close', (reason) => console.log('Stream closed because of', reason));
// "open" event is emitted on first .open() call and each time a new open is attempted
stream.on('open', () => console.log('Stream open...'));
// "ping" event is emitted each time a ping is received from the source stream
stream.on('ping', () => console.log('Received ping'));
```

启用后, 自动重试行为将遵循无限指数回放模式 . 您可以更改默认的计时和此类重试的最大次数 :

```js
stream.open({
  autoRetry: true,
  // Factor used to compute exponential backoff delays, defaults to 1.25
  backoffFactor: 1.5,
  // First iteration timeout in ms, also used to compute exponential backoff delays, defaults to 1500
  initRetryTimeout: 2000,
  // Maximum number of consecutive iterations the auto retry behaviour can do, defaults to Infinity
  maxRetryCount: 6,
});
```

## 日志流 (v4)

```js
import { ApplicationLogStream } from '@clevercloud/client/esm/streams/application-log.js';

// Load and cache config and tokens
const API_HOST = 'https://api.clever-cloud.com';
const tokens = {
  OAUTH_CONSUMER_KEY: 'your OAUTH_CONSUMER_KEY',
  OAUTH_CONSUMER_SECRET: 'your OAUTH_CONSUMER_SECRET',
  API_OAUTH_TOKEN: 'your API_OAUTH_TOKEN',
  API_OAUTH_TOKEN_SECRET: 'your API_OAUTH_TOKEN_SECRET',
};

// Create an EventsStream instance (appId is optional)
const logsStream = new ApplicationLogStream({
  apiHost: API_HOST,
  tokens,
  ownerId: 'YYY',
  appId: 'XXX',
  // optionnal auto retry config
  // retryConfiguration: {
  //   enabled: true,
    // backoffFactor: number,
    // initRetryTimeout: number,
    // maxRetryCount: number,
  // },
  // optionnal logs request params
  // since: Date,
  // until: Date,
  // service: string[],
  // limit: number,
  // deploymentId: string,
  // instanceId: string[],
  // filter: string,
  // field: string[],
  // throttleElements: number,
  // throttlePerInMilliseconds: number,
});

logsStream
  .on('open', (event) => console.debug('stream opened!', event))
  .on('error', (event) => console.error('error', event.error))
  .onLog((event) => console.log(event.data.date, event.data.message));

logsStream.start();

// You can also pause the stream
logsStream.pause();

// And resume it
logsStream.resume();
```

## 许可证

本项目根据以下规定获得许可证: [阿帕奇 - 2.0](https://spdx.org/licenses/Apache-2.0.html)。 。 。 .

## 常见问题

### @clevercloud/client 是什么？

JavaScript REST 客户端和用于智能云 API的 utils

### 如何安装 @clevercloud/client？

在项目目录运行 npm install @clevercloud/client，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：eventsource（^4\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @clevercloud/client 支持 TypeScript 吗？

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

### @clevercloud/client 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @clevercloud/client 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @clevercloud/client 可以商用吗？

@clevercloud/client 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @clevercloud/client 的下载量有多少？

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

### @clevercloud/client 还在维护吗？

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