# @featbit/js-client-sdk 中文文档

规范地址：https://npmcn.com/package/%40featbit/js-client-sdk/

版本：4\.4\.2
npm 元数据更新时间：2026-11-03T15:13:06.133Z
中文译文更新时间：2026-11-14T12:48:39.388Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.7 MB，873 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2024-04-15T09:04:38.699Z
- 最新版本发布：2026-11-03T15:13:05.973Z
- 近 30 天下载量：79167（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 22 个）

## 中文简介

[https://github.com/featbit/featbit-js-client-sdk 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/featbit/featbit-js-client-sdk)

## 安装

```sh
npm install @featbit/js-client-sdk
```

也可以使用：`pnpm add @featbit/js-client-sdk`、`yarn add @featbit/js-client-sdk`、`bun add @featbit/js-client-sdk`

## README

> **请注意**
> 
> 如果您正在使用 SDK 的 v1 或 v2, 请参见此 [医生](https://github.com/featbit/featbit-js-client-sdk/tree/v2)

# JavaScript 的 FeatBit 客户端 SDK

## 导言

这是100%开源功能旗管理平台的客户端- Side SDK [费特比特](https://github.com/featbit/featbit)。 。 。 .

要注意,这是客户端SDK,它旨在用于单个用户上下文,可以是移动,桌面或嵌入式应用程序. 这个SDK只能运行在浏览器环境中,不适合NodeJs应用.

## 开始

### 安装

```bash
npm install --save @featbit/js-client-sdk
```

### 先决条件

在使用SDK之前,需要获得环境秘密(sdkKey)和SDK URL.

遵循以下文档获取这些值

-   [如何让环境秘密](https://docs.featbit.co/sdk/faq#how-to-get-the-environment-secret)
-   [如何获得 SDK URL](https://docs.featbit.co/sdk/faq#how-to-get-the-sdk-urls)

### 快速启动

以下代码显示: `@featbit/js-client-sdk`。 。 。 .

```javascript
import { FbClientBuilder, UserBuilder } from "@featbit/js-client-sdk";

const bob = new UserBuilder('a-unique-key-of-user')
    .name('bob')
    .custom('age', '18')
    .custom('country', 'FR')
    .build();

// setup SDK client with websocket streaming
const fbClient = new FbClientBuilder()
    .sdkKey("your_sdk_key")
    .streamingUri('ws://localhost:5100')
    .eventsUri("http://localhost:5100")
    .user(bob)
    .build();

(async () => {
  // wait for the SDK to be initialized
  try {
    await fbClient.waitForInitialization();
  } catch(err) {
    // failed to initialize the SDK
    console.log(err);
  }

  // flag to be evaluated
  const flagKey = "game-runner";

  // evaluate a feature flag for a given user
  const boolVariation = await fbClient.boolVariation(flagKey, false);

  // switch user
  const alice = new UserBuilder('another-unique-key-of-user')
      .name('alice')
      .custom('country', 'UK')
      .custom('age', 36)
      .build();
  
  await fbClient.identify(alice);
})();
```

## 实例

-   [网络应用](https://npmcn.com/package/%40featbit/js-client-sdk/examples/console-app)
-   关于如何使用 FeatBit with React,请参见 [反应 - 客户端 - sdk](https://github.com/featbit/featbit-react-client-sdk)

## SDK 软件

### Fb 用户

这个 `FbClient` 是提供 FeatBit 服务器访问的 SDK 的核心 。 申请应在申请的周期内立即提出一个实例.

`FbClientBuilder` 用于构建一个 `FbClient` 举个例子 构建者将显示配置 SDK 的方法,并最终创建 `FbClient` 举个例子.

#### 使用流线的 FbClient

```javascript
import { FbClientBuilder, UserBuilder } from "@featbit/js-client-sdk";

const user = new UserBuilder('a-unique-key-of-user')
    .name('bob')
    .build();
    
const fbClient = new FbClientBuilder()
    .sdkKey("your_sdk_key")
    .streamingUri('ws://localhost:5100')
    .eventsUri("http://localhost:5100")
    .user(user)
    .build();
```

#### 使用投票的 Fb 客户端

```javascript
import { FbClientBuilder, UserBuilder, DataSyncModeEnum } from "@featbit/js-client-sdk";

const user = new UserBuilder('a-unique-key-of-user')
    .name('bob')
    .build();

const fbClient = new FbClientBuilder()
    .sdkKey("your_sdk_key")
    .dataSyncMode(DataSyncModeEnum.POLLING)
    .pollingUri('http://localhost:5100')
    .eventsUri("http://localhost:5100")
    .pollingInterval(10000)
    .build();
```

#### 与倒计时相接

在使用流模式时,如果启动时无法建立WebSocket连接,SDK可以自动倒回投票. 这是 **默认禁用** 必须明确启用.

> **_注:_** `pollingUri` 在允许投票倒计时必须设定,否则倒计时没有投票终点.

```javascript
import { FbClientBuilder, UserBuilder } from "@featbit/js-client-sdk";

const user = new UserBuilder('a-unique-key-of-user')
    .name('bob')
    .build();

// opt in to polling fallback — pollingUri is required
const fbClient = new FbClientBuilder()
    .sdkKey("your_sdk_key")
    .streamingUri('ws://localhost:5100')
    .pollingUri('http://localhost:5100')   // required for fallback
    .eventsUri("http://localhost:5100")
    .enablePollingFallback(true)
    .user(user)
    .build();
```

#### 用户

`IUser` 定义正在评价特征标记的用户的属性。 IUser有两个内置属性:密钥和名. 一个IUser唯一的强制属性是密钥,密钥必须单独识别每个用户.

除了这些内置属性外,您还可以使用 `custom(string key, string value)` 方法。 内置属性和自定义属性都可以在瞄准规则中被引用,并包含在分析数据中.

`UserBuilder` 用于构建一个 `IUser` 举个例子 构建者暴露出配置 IUser 的方法,最后创建 IUser 实例.

```javascript
import { UserBuilder } from "@featbit/js-client-sdk";

const bob = new UserBuilder("unique_key_for_bob")
    .name("Bob")
    .custom('age', 18)
    .custom('country', 'FR')
    .build();
```

### 诱饵

如果您已经拥有可用的特性标记,您可以将其传递给 SDK 而不是从远程请求 .

> **_注:_** 有效的缓存快照优先于靴子陷阱,包括空快照或存档旗. 只有当不存在有效的缓存且存储为空时才会使用 Bootstrap. 远程值用相同的密钥来替换靴子值; 仅本地的靴子值从远程全快照中幸存了省略值 。 一旦一个远程值或归档替换了靴子值,之后的完整快照并不能恢复该靴子值.

```javascript
// define the option with the bootstrap parameter
const options = {
  ...
  bootstrap = [{
    // feature flag key name
    id: string,
    // variation value
    variation: string,
    // variation data type, string will be used if not specified
    variationType: VariationDataType
  }]
}

const fbClient = new FbClientBuilder(options).build();
// or
const fbClient = new FbClientBuilder()
    //... other options
    .bootstrap(options.bootstrap)
    .build();
```

### 锁定器

默认日志使用 **无** 作为日志级别,这意味着它不会输出任何东西。 如果默认日志不符合您的需要, 您有两个选项 .

#### 使用不同的日志级别

```javascript
const fbClient = new FbClientBuilder()
    .logLevel('debug') // possible log levels: 'debug', 'info', 'warn', 'error', 'none'
    ...
    .build();

// or
const options = {
  ...
  logLevel: 'debug'
}

const fbClient = new FbClientBuilder(options).build();
```

#### 定义自己的日志

您的日志必须执行 **ILOGER 浏览器** 界面,我们提供了 **Basic 潜行器**你可以像这样使用:

```javascript
const logger = new BasicLogger({
    level: 'debug', // possible log levels: 'debug', 'info', 'warn', 'error', 'none'
    destination: console.log
});

const fbClient = new FbClientBuilder()
    .logger(logger)
    ...
    .build();

// or
const options = {
  ...
  logger: logger
}

const fbClient = new FbClientBuilder(options).build();
```

注意日志选项的优先级高于日志级 。 如果您通过两个选项, 日志级将被忽略 .

### 评价

初始化后,SDK在当地拥有了所有的特性旗,不需要请求远程服务器来进行任何特性旗评价. 所有评价都是在当地同步进行的,平均评价时间不到一毫秒.

有一个 `variation` 返回旗帜值的方法,以及 `variationDetail` 返回对象的方法 说明如何为每种类型确定数值.

-   bulVariation/boolVariation 详情
-   字符串变化/字符串变化
-   数字变化/数字变化
-   json 变化/json 变化

变位调取特性旗键和默认值. 如果有任何错误,则无法 评价旗帜(例如,特性旗帜密钥不匹配任何已存在的旗帜),默认值会被返回.

```javascript
// flag to be evaluated
const flagKey = "game-runner";

// evaluate a feature flag for a given user
const boolVariation = await fbClient.boolVariation(flagKey, false);

// evaluate a boolean flag for a given user with evaluation detail
const boolVariationDetail = await fbClient.boolVariationDetail(flagKey, false);
```

### 离线模式

在某些情况下,你可能要停止 远程呼叫费特比特。 这是如何:

```javascript
import { FbClientBuilder } from "@featbit/browser-server-sdk";

const fbClient = new FbClientBuilder()
    //... other options
    .offline(true)
    .build();

```

当启用离线模式时,您应该向旗下提供 [拖带](https://npmcn.com/package/%40featbit/js-client-sdk/#readme-bootstrap) 选项, 否则,SDK会归还你传递给 `variation` 方法.

### 保留用户缓存

内置商店默认最多保留了5个用户上下文,包括当前上下文. 一个上下文包括用户的属性,因此改变属性可以选择另一个缓存条目. 历史条目在7天后失效,未经选择或更新. 配置这些限制 与 `.maxCachedUsers(5)` 财务报告和审定财务报表 `.userCacheTtl(7 * 24 * 60 * 60 * 1000)`,或相应的 构造器选项 。 这两个值必须是正安全整数;TTL为毫秒.

| 选项/构建方法 | 默认 | 目的 |
| --- | --- | --- |
| `maxCachedUsers` | `5` | 最大保留用户上下文,包括当前上下文 |
| `userCacheTtl` | `604800000` (7天) (中文(简体) ) | 历史用户缓存已过期, 以毫秒计 |
| `fullSyncInterval` | `86400000` (24小时) | 在线全刷新间隔, 以毫秒为单位, 有 ± 10% 的焦距 |

无效值会回落到默认值,并通过所配置的日志报告 .

这些选项适用于内置商店,而不是应用程序自定义的自定义商店.

### 存档并删除了旗帜

当服务器响应标记了旗帜时 `matchReason: "flag archived"`,内置商店删除其完整的评价数据,只保留其密钥,版本,出处和存档标记. 变异方法返回提供的默认值,以及 `getAllVariations()` 不包括旗帜。 该标记使更古老的补丁无法将旗帜带回. 后被接受的无存档值使其再次被提供.

一个成功的全快照可以去除被服务器省略的远程旗帜和归档标记. 这将调和断开时丢失的删除或归档更改 。 在SDK收到存档更新或权威全快照之前,缓存值仍然可以返回;定期刷新不是立即删除通知. 已归档的标记保留在活动快照内,直到被更新的数据所取代或被完整的快照所去掉. 历史用户缓存以计数和闲置时间为界,不是字节大小.

### 活动

#### 等着准备

要了解客户端何时准备好,可以使用两种机制之一:事件或承诺.

客户对象可以放出JavaScript事件. 当它从服务器接收到初始旗下值时, 它会发出一个已准备好的事件 。 您可以聆听此事件以确定客户端何时准备好评价旗帜 .

```javascript
fbClient.on('ready', () => {
  var flagValue = fbClient.variation("YOUR_FEATURE_KEY", defaultValue);
});
```

或者, `waitForInitialization()` 在当前用户上下文初始化成功后与客户端解决。 使用 `getAllVariations()` 以获取评估过的旗帜。 离线初始化使用缓存或靴子化数据. 每个识别开始一个新的准备周期.

```javascript
await fbClient.waitForInitialization();
const featureFlags = await fbClient.getAllVariations();
```

初始化在无法恢复的同步错误或何时失败 `startWaitTime` 过期( 默认为5秒) 。 初始化超时不能停止背景同步;后期成功响应可以使客户端做好准备. 关闭客户端或启动另一个 DID 拒绝未完成的初始化等待 .

#### 订阅标记更改

订阅是注册在 `on`,例如UI组件需要重读一面旗帜. 承诺答复最多一次发出 `update` 包含平面的事件 `string[]` 键,然后是 `update:<key>` 每个键。 听者看到全部承诺的批量。 变化包括增加,去除/存档,还原,或价值或价值类型的变化. 重复的存档,拒绝的 stale 补丁,或者只使用元数据的更改不会发出更新.

对于已存档或已删除的密钥,在调用器内重新读取返回提供的默认值 。 完整快照可能会释放服务器省略了旗帜的去除事件. 切换用户也可能在所选缓存不同时发出变化.

有两种订阅表格:

-   订阅任何特性旗的更改

```javascript
fbClient.on('update', (keys: string[]) => {
  // do something when any feature flag changes
});

```

-   订阅特定特性旗的更改

```javascript
// replace feature_flag_key with your feature flag key
fbClient.on('update:feature_flag_key', (key) => {
  const myFeature = fbClient.variation('feature_flag_key', defaultValue);
});

```

### 初始化后切换用户

如果用户在经过了某些过程后有所改变,例如登录,可以使用以下方法在初始化后设置用户.

```javascript
await fbClient.identify(user);
```

### 数据同步

我们用 **网络安全套** 或者说 **投票** ,使本地数据与服务器同步,然后默认将其存储到本地Storage。 当特性旗或其相关数据有任何更改时,此更改会被推向 SDK,平均同步时间会少于 **百分点** 如果配置了 WebSocket 。 但一旦问题消失, 便会自动恢复.

内置同步器在启动时和每次启动后请求完整快照 `identify`,即使缓存光标存在。 在获取快照时仍然可以使用现有旗帜 。 普通重联使用递增同步,直到下一次完全刷新到期.

完全刷新默认为24小时,随机时间为±10%。 以毫秒配置间隔 `new FbClientBuilder({ fullSyncInterval: 24 * 60 * 60 * 1000 })` 或者说 `.fullSyncInterval(...)`;必须是正安全整数。 只有成功承诺的完整响应重排间隔 。 补丁响应, HTTP 304, 和失败的请求留下全部更新等待 。 一个空的全快照会去掉以前的远程旗帜,然后将光标重置为零.

流取刷新取代了WebSocket连接并请求时间戳为0,每30秒重试一次等待的全刷新. 投票要求获得下一次预定投票的完整快照。 两种模式在页面可见或被恢复时检查过期,投票倒计时共享相同的刷新状态. 关闭客户端会删除刷新的计时器和页面收听器;离线模式将不创建. 自定义同步器必须执行自己的刷新调度 .

### 网络故障处理

由于所有数据都在当地存储在本地Storage中,在以下情况下,当暂时没有互联网连接时,SDK仍然会工作:

-   它已经收到以前连接的数据
-   页:1 `fbClient.bootstrap(featureFlags)` 方法使用所有必要的特征标记

在此期间,SDK会尝试以递增间隔重新连接到服务器,这可以确保网络连接恢复后网络口被恢复.

### 禁用事件收藏

默认情况下,SDK会自动向FeatBit服务器发送事件(旗下评价事件和A/B测试的度量事件),除非SDK处于离线模式.

如果您喜欢在SDK处于在线模式时禁用此事件收藏, 您可以使用 `disableEvents` 选项.

```javascript
import { FbClientBuilder } from "@featbit/browser-server-sdk";

const fbClient = new FbClientBuilder()
        .disableEvents(true)
        .build();
```

旗子评价事件收藏也由每个旗子控制 `insightsEnabled` 从 FeatBit 服务器收到的设置 :

-   `false`: 禁用该旗帜的评价事件收藏,而不改变其评价结果.
-   `true` 或缺:允许评价事件收集,但需启用全SDK事件收集.

`disableEvents` 必须是 `false` (默认)和SDK必须在线供每个旗子的见解来收集评价事件. 设置 `insightsEnabled` 改为 `true` 不覆盖 `disableEvents` 或离线模式。 这个 `insightsEnabled` 设置不影响自定义的度量事件 `track()`;这些仍受SDK全局事件收集设置的约束.

### 实验(A/B/n测试)

我们支持网页浏览和点击的自动实验, 你只需要把你的实验设置在我们SaaS平台上, 那你应该可以在实验开始后 近实时看到结果.

如果你需要更多的控制 实验数据发送到我们的服务器, 我们提供一个方法 发送自定义事件.

```javascript
fbClient.track(eventName, numericValue);
```

**数值** ,默认值为 **1.0 国家**。 。 。 .

确保 `track` 在调用相关特性旗后调用, 否则自定义事件将不会包含 进入实验结果.

## 获得支持

-   如果你有关于使用这个sdk的具体问题 我们鼓励你 改为 [趁机问吧](https://join.slack.com/t/featbit/shared_invite/zt-1ew5e2vbb-x6Apan1xZOaYMnFzqZkGNQ)。 。 。 .
-   如果您遇到错误或想要请求 特性, [提交问题](https://github.com/featbit/dotnet-server-sdk/issues/new)。 。 。 .

## 另见

-   [连接到 JavaScript Sdk](https://docs.featbit.co/getting-started/connect-an-sdk#javascript)

## 常见问题

### @featbit/js-client-sdk 是什么？

https://github\.com/featbit/featbit-js-client-sdk 互联网档案馆的存檔,存档日期2013-12-22

### 如何安装 @featbit/js-client-sdk？

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

### @featbit/js-client-sdk 支持 TypeScript 吗？

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

### @featbit/js-client-sdk 支持 ESM 还是 CommonJS？

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

### @featbit/js-client-sdk 可以商用吗？

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

### @featbit/js-client-sdk 的下载量有多少？

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

### @featbit/js-client-sdk 还在维护吗？

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