# @configcat/sdk 中文文档

规范地址：https://npmcn.com/package/%40configcat/sdk/

版本：1\.1\.0
npm 元数据更新时间：2026-05-27T15:04:18.641Z
中文译文更新时间：2026-11-10T15:18:13.979Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.8 MB，160 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2024-11-08T16:09:12.079Z
- 最新版本发布：2026-05-27T15:04:18.302Z
- 近 30 天下载量：566565（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 1 个）

## 中文简介

配置(ConfigCat)是一种服务,它允许您在不实际部署新代码的情况下管理您的特性和配置.

## 安装

```sh
npm install @configcat/sdk
```

也可以使用：`pnpm add @configcat/sdk`、`yarn add @configcat/sdk`、`bun add @configcat/sdk`

## README

# JavaScript 配置Cat SDK

[![JS SDK CI](https://github.com/configcat/js-unified-sdk/actions/workflows/js-sdk-ci.yml/badge.svg?branch=master)](https://github.com/configcat/js-unified-sdk/actions/workflows/js-sdk-ci.yml) [![Quality Gate Status](https://img.shields.io/sonar/quality_gate/configcat_js-unified-sdk?logo=SonarCloud&server=https%3A%2F%2Fsonarcloud.io)](https://sonarcloud.io/project/overview?id=configcat_js-unified-sdk) [![SonarCloud Coverage](https://img.shields.io/sonar/coverage/configcat_js-unified-sdk?logo=SonarCloud&server=https%3A%2F%2Fsonarcloud.io)](https://sonarcloud.io/project/overview?id=configcat_js-unified-sdk) [![Known Vulnerabilities](https://snyk.io/test/github/configcat/js-unified-sdk/badge.svg?targetFile=package.json)](https://snyk.io/test/github/configcat/js-unified-sdk?targetFile=package.json) [![License](https://img.shields.io/github/license/configcat/js-unified-sdk.svg)](https://github.com/configcat/js-unified-sdk/blob/master/LICENSE) [![JSDELIVR](https://data.jsdelivr.com/v1/package/npm/@configcat/sdk/badge)](https://www.jsdelivr.com/package/npm/@configcat/sdk) [![NPM](https://nodei.co/npm/@configcat/sdk.png)](https://www.npmjs.com/package/@configcat/sdk)

JavaScript 配置 Cat SDK 为您的应用程序提供了简单的集成 [配置凯特](https://configcat.com/)。 。 。 .

这个寄存器为JavaScript平台托管了现代ConfigCat SDK. 与遗留的针对平台的一揽子计划不同,它提供了一个支持多个JS环境的单一,统一的国家预防机制一揽子计划.

新的SDK结合并因此取代了这些软件包:

-   [配置常见](https://www.npmjs.com/package/configcat-common)
-   [配置猫js](https://www.npmjs.com/package/configcat-js)
-   [配置- js- ssr](https://www.npmjs.com/package/configcat-js-ssr)
-   [配置cat-js-铬-扩展](https://www.npmjs.com/package/configcat-js-chromium-extension)
-   [配置猫节点](https://www.npmjs.com/package/configcat-node)

新的SDK保持了很强的后向相容性,使得它成为了上述套件的倒置取而代之. 在大多数情况下,您只需要将旧包替换为新包并调整导入的指定符,如所示 [这里](https://npmcn.com/package/%40configcat/sdk/#readme-1-install-and-import-package)。 。 。 .

## 开始

### 1\. 安装和进口包:

#### _通过国家预防机制_

首先安装 [国家防范机制一揽子计划](https://npmjs.com/package/@configcat/sdk)数字 :

```PowerShell
npm i @configcat/sdk
```

然后导入到您的应用程序中 :

-   前端应用程序和浏览器中运行的Web Works:
    
    ```js
    import * as configcat from "@configcat/sdk/browser";
    ```
    
-   节点.js后端应用程序 :
    
    ```js
    import * as configcat from "@configcat/sdk/node";
    ```
    
-   Deno后端应用程序 :
    
    ```js
    import * as configcat from "npm:@configcat/sdk/deno";
    ```
    
    要做到这一点,你可能需要使 [不稳定的bym](https://deno.com/blog/node-to-deno-challenge#what-are-all-these-unstable-node-compatibility-settings) 特性或调整 [导入映射](https://docs.deno.com/runtime/fundamentals/modules/#differentiating-between-imports-or-importmap-in-deno.json-and---import-map-option)。 。 。 .
    
-   Bun后端应用程序 :
    
    ```js
    import * as configcat from "@configcat/sdk/bun";
    ```
    
-   云浮工人:
    
    ```js
    import * as configcat from "@configcat/sdk/cloudflare-worker";
    ```
    
-   基于铬的浏览器(Chrome, Edge等)的扩展:
    
    ```js
    import * as configcat from "@configcat/sdk/chromium-extension";
    ```
    

> \[注\] 请注意,亚道进口需要您的捆绑商支持 [出口](https://nodejs.org/api/packages.html#exports) package.json 字段,引入于 Node.js v12.7. **在不可能发生捆绑兼容性问题时**,您可以从主入口返回导入 `@configcat/sdk`基本上,这是另一个切入点 到节点。js构建,但是,如果你的捆绑者识别 [浏览器](https://github.com/defunctzombie/package-browser-field-spec) package.json 字段,它也会在您的浏览器应用程序中无缝工作.

> \[注\] 子路径导入工作 **类型脚本**,必须设置 [模块分辨率](https://www.typescriptlang.org/tsconfig/#moduleResolution) 选项到 `node16`, (中文(简体) ), `nodenext` 或者说 `bundler` 在你身边 `tsconfig.json`对于超过4.7的TypeScript版本,如果无法提供这些选项,则需要返回模块分辨率 `node` 从主要入境点导入 `@configcat/sdk`。 。 。 .

#### _通过 CDN_

从 CDN 服务器直接导入软件包到您的应用程序 :

-   前端应用程序和浏览器中运行的Web Works:
    
    ```html
    <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@configcat/sdk@latest/dist/configcat.browser.umd.min.js"></script>
    ```
    
    或者说
    
    ```html
    <script type="module">
      import * as configcat from "https://cdn.jsdelivr.net/npm/@configcat/sdk@latest/dist/configcat.browser.esm.min.js";
    </script>
    ```
    
-   基于铬的浏览器(Chrome, Edge等)的扩展:
    
    ```js
    <script type="module">
      import * as configcat from "https://cdn.jsdelivr.net/npm/@configcat/sdk@latest/dist/configcat.chromium-extension.esm.min.js";
    </script>
    ```
    

### 2\. 前往 [配置 Cat 剪贴板](https://app.configcat.com/sdkkey) 让你的 _SDK 密钥_数字 :

![SDK-KEY](https://raw.githubusercontent.com/configcat/js-unified-sdk/master/media/readme02-3.png "SDK-KEY")

### 3\. 创建一个 _配置卡特客户端_ 实例:

```js
const configCatClient = configcat.getClient("#YOUR-SDK-KEY#");
```

> \[注\] 您可以使用 SDK 键获取单通客户端实例 `getClient("<sdkKey>")` 工厂功能. (然而,请铭记,随后的电话是: `getClient()` 与 _相同的 SDK 密钥_ 返回 a _共享_ 客户实例,这是由第一个呼叫设置的。 )

### 4\. 获取您的设置值:

同步/等待方式 :

```js
const value = await configCatClient.getValueAsync('isMyAwesomeFeatureEnabled', false);

if (value) {
  do_the_new_thing();
} else {
  do_the_old_thing();
}
```

或承诺方式:

```js
configCatClient.getValueAsync('isMyAwesomeFeatureEnabled', false)
  .then((value) => {
    if (value) {
      do_the_new_thing();
    } else {
      do_the_old_thing();
    }
  });
```

## 获取针对用户的设置值

此功能允许您通过传递一个 [用户对象](https://configcat.com/docs/targeting/user-object/) 改为 `getValueAsync()`。 。 。 .

更多信息:目标 [这里](https://configcat.com/docs/advanced/targeting/)。 。 。 .

```js
const userObject = { identifier: "#USER-IDENTIFIER#" };
const value = await configCatClient.getValueAsync('isMyAwesomeFeatureEnabled', false, userObject);

if (value) {
  do_the_new_thing();
} else {
  do_the_old_thing();
}
```

## 样本/软件

-   [普通 HTML + 联合来文](https://github.com/configcat/js-unified-sdk/tree/master/samples/html)
-   [使用 ECMAScript 模块系统的 Plain HTML + JS](https://github.com/configcat/js-unified-sdk/tree/master/samples/html-esm)
-   [在 Web Worker 中运行 SDK 的 Plain HTML + TS](https://github.com/configcat/js-unified-sdk/tree/master/samples/web-worker)
-   [角网应用程序样本](https://github.com/configcat/js-unified-sdk/tree/master/samples/angular-sample)
-   [样本反应网络应用程序](https://github.com/configcat/js-unified-sdk/tree/master/samples/react-sample)
-   [样本反应原生应用程序](https://github.com/configcat/js-unified-sdk/tree/master/samples/react-native-sample)
-   [Vue SSS 网络应用程序样本](https://github.com/configcat/js-unified-sdk/tree/master/samples/vue-ssr-sample)
-   [标本节点控制台应用程序](https://github.com/configcat/js-unified-sdk/tree/master/samples/node-console)
-   [使用 ECMAScript 模块系统的样本节点控制台应用程序](https://github.com/configcat/js-unified-sdk/tree/master/samples/node-console-esm)
-   [使用 TypeScript 的样本节点控制台应用程序](https://github.com/configcat/js-unified-sdk/tree/master/samples/ts-node-console)
-   [使用 TypeScript 和 ECMAScript 模块系统的样本节点控制台应用程序](https://github.com/configcat/js-unified-sdk/tree/master/samples/ts-node-console-esm)
-   [使用 Express 和 Docker 的 sample Node.js 应用程序](https://github.com/configcat/js-unified-sdk/tree/master/samples/node-expresswithdocker)
-   [关于如何获取特性旗变化实时更新的节点Js样本应用程序](https://github.com/configcat/js-unified-sdk/tree/master/samples/node-realtimeupdate)
-   [Deno 控制台样本应用程序](https://github.com/configcat/js-unified-sdk/tree/master/samples/deno-console)
-   [样机控制台应用程序](https://github.com/configcat/js-unified-sdk/tree/master/samples/bun-console)
-   [云旗工人样本](https://github.com/configcat/js-unified-sdk/tree/master/samples/cloudflare-worker)
-   [Chrome 扩展样本](https://github.com/configcat/js-unified-sdk/tree/master/samples/chrome-extension)

## 投票模式

ConfigCat SDK支持从 ConfigCat CDN 获取特征旗和设置的三种不同的投票策略. 一旦下载了最新数据,它就会被存储在缓存中,然后SDK使用缓存数据来评价特征旗和设置. 更多信息,请查看投票方式及投票方式 [配置目录](https://configcat.com/docs/sdk-reference/js/overview/#polling-modes)。 。 。 .

## 敏感信息处理

前端/移动 SDK在用户的浏览器/设备中运行. 他们下载一个 [配置 JSON](https://configcat.com/docs/requests/) 来自 CfigCat 的 CDN 服务器的文件。 由于SDK密钥包含在本文件的URL路径中,您的用户既可以访问SDK密钥,也可以访问配置JSON的内容(包括特征旗密钥,特征旗值,目标规则,百分数选项等)

然而,SDK密钥提供只读访问:它只允许下载您配置的JSON文件,但不能用于修改您配置Cat账户中相应的配置.

如果您想阻止您的用户访问您的 SDK 密钥和您的配置 JSON 文件的内容, 我们建议仅在您的后端服务中使用 SDK 。 然后,您可以为您的前端/移动应用程序提供一个安全的 API 端点,用于为您的用户评价特征标记和设置 .

我们还建议使用 [机密文本参照系统](https://configcat.com/docs/targeting/targeting-rule/user-condition/#confidential-text-comparators) 用于前端/移动 SDK 的特性标记和设置的目标规则.

## 软件包内容

目前 `@configcat/sdk` 国家防范机制一揽子计划包括以下图书馆建筑:

-   `dist/configcat.browser.umd.min.js` - 通过 HTML 在旧浏览器中引用库 `<script>` 标签 :
    -   使用UMD捆绑格式.
    -   目标ES5并包括所有必要的多填充.
    -   不提供脚本类型定义.

-   `dist/configcat.browser.esm.min.js` - 通过 HTML 在更新浏览器中引用库 `<script>` 标签 :
    -   使用标准的ECMAScript模块格式.
    -   目标ES2015并包括所有必要的多填充.
    -   不提供脚本类型定义.
-   `dist/configcat.chromium-extension.esm.js` - 通过 HTML 引用基于 Chromium 的浏览器扩展库 `<script>` 标签 :
    -   使用标准的ECMAScript模块格式.
    -   目标ES2017并包括所有所需的多填充.
    -   不提供脚本类型定义.
-   `lib/cjs/` - 对于不支持ES模块的旧版本Node.js和捆绑器:
    -   使用遗留的 CommunityJS 模块格式.
    -   ES 2017目标,包括除 `Promise` 特性.
    -   提供了TypeScript类型定义.
-   `lib/esm/` - 对于Node.js、Deno、Bun和捆绑机的现代版本:
    -   使用标准的ECMAScript模块格式.
    -   ES 2017目标,包括除 `Promise` 特性.
    -   提供了TypeScript类型定义.

> \[注\] 请注意: `lib` 构建一个相对新的ECMAScript标准的目标. 根据 [节点. 绿色](https://node.green/),这与 [所支持的节点.js版本](https://npmcn.com/package/%40configcat/sdk/#readme-platform-compatibility)然而,如果您使用捆绑器并想要瞄准没有ES2017支持的浏览器,请确保捆绑器的配置能够降级语言语法. 如果你想一直到ES5, 那你需要包含一个多填充器 `Promise` 特征也一样.

## 平台兼容性

这个SDK应该兼容所有被广泛使用的现代JS运行时间(执行引擎)和捆绑机.

这个SDK是 [测试](https://github.com/configcat/js-unified-sdk/blob/master/.github/workflows/js-sdk-ci.yml) 相对于以下运行时间:

-   @ configcat/sdk/浏览器 :
    -   铬(稳定、最新、β)
    -   铬 (71.0.3556.0, 72.0.3626.0, 80.03987.0)
    -   Firefox (84. 0, 最新, 最新β)
    -   萨法里(最新)
-   @ configcat/ sdk/ bun: 页面存档备份,存于互联网档案馆
    -   在 Windows / Ubuntu / macOS 上的 Bun( v1.1. 0, 最新稳定)
-   @ configcat/ sdk/ deno : (中文(简体) )
    -   在 Windows / Ubuntu / macOS 上的 Deno( v1.31, v1.46, 最新稳定)
-   @ configcat/ sdk/ 节点 :
    -   (v14.x, v16.x, v18.x, v20.x, v22.x, v24.x) 在Windows / Ubuntu / macOS上的节点
-   @configcat/sdk/cloudflare-worker: 翻译:
    -   工人 (2026-04-02) (中文(简体) )
-   @ configcat/sdk/铬-扩展:
    -   铬(稳定、最新、β)
    -   铬 (72.0.3626.0, 80.0.3987.0)

SDK与TypeScript v4.0.2或更新型兼容. 更早的版本可能有用,但是没有经过测试,因此没有得到官方支持.

这些测试在每次调用请求上进行,在每次部署前进行,每天进行.

您可以查看样本运行 [这里](https://github.com/configcat/js-unified-sdk/actions/runs/16875243620)。 。 。 .

> \[注\] 我们努力为联合来文的各种运行时间提供广泛的支持并建设工具。 如果你还在某个平台上遇到SDK的问题,请打开一个 [GitHub 问题](https://github.com/configcat/js-unified-sdk/issues/new/choose) 或者说 [联系支持](https://configcat.com/support)。 。 。 .

## 解决问题

### 确保您安装了合适的节点.js版本

你可能会碰到错误的节点版本造成的错误。 为了保证您使用推荐的节点.js版本遵循这些步骤.

1.  有 nvm(节点版本管理器 - [https://github.com/nvm-sh/nvm 页面存档备份,存于互联网档案馆](https://github.com/nvm-sh/nvm) 已安装:
2.  运行 `nvm install`。这将安装兼容的 Node.js 版本.
3.  运行 `nvm use`。这将使用相容的 Node.js 版本.

## 需要帮忙吗?

[https://configcat.com/ support (中文(简体) )](https://configcat.com/support)

## 捐款

欢迎捐款。 更多信息请改为: [贡献准则](https://npmcn.com/package/%40configcat/sdk/CONTRIBUTING.md)。 。 。 .

## 关于配置卡特

ConfigCat是一个功能旗和配置管理服务,可以将发布与部署区分开来. 您可以使用 [配置 Cat 剪贴板](https://app.configcat.com/) 即使在他们部署之后。 CfigCat 允许您针对基于区域,电子邮件或任何其他自定义用户属性的特定用户组.

配置卡特是一个 [主机特性旗服务](https://configcat.com/)。管理跨前端、后端、移动、桌面应用程序的特性切换. [暗地发射的替代品](https://configcat.com/). 管理app + 特征旗 SDK.

-   [其他平台的官方配置Cat SDK](https://github.com/configcat#-official-open-source-sdks)
-   [文档](https://configcat.com/docs)
-   [博客](https://configcat.com/blog)

## 常见问题

### @configcat/sdk 是什么？

配置\(ConfigCat\)是一种服务,它允许您在不实际部署新代码的情况下管理您的特性和配置\.

### 如何安装 @configcat/sdk？

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

### @configcat/sdk 支持 TypeScript 吗？

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

### @configcat/sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @configcat/sdk 可以商用吗？

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

### @configcat/sdk 的下载量有多少？

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

### @configcat/sdk 还在维护吗？

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