# @featbit/node-server-sdk 中文文档

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

版本：1\.4\.1
npm 元数据更新时间：2026-11-03T14:44:56.577Z
中文译文更新时间：2026-11-14T12:48:47.214Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：864 kB，915 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2024-01-08T09:16:29.054Z
- 最新版本发布：2026-11-03T14:44:56.381Z
- 近 30 天下载量：56510（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 4 个）

## 中文简介

[https://github.com/featbit/featbit-node-server-sdk 页面存档备份,存于互联网档案馆](https://github.com/featbit/featbit-node-server-sdk)

## 安装

```sh
npm install @featbit/node-server-sdk
```

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

## README

# FeatBit 服务器- Side SDK 用于节点.js

## 导言

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

FeatBit Server-Side SDK为Node.js设计,主要用于网络服务器和应用等多用户系统. 它并非用于桌面和嵌入式系统应用程序.

## 数据同步

我们用 **网络安全套** 或者说 **投票** 使本地数据与服务器同步,然后默认将其存储在内存中。 当特性旗或其相关数据有任何更改时,此更改会被推向 SDK,平均同步时间会少于 **百分点**。请注意WebSocket/Polling连接可能因互联网停用而中断,但一旦问题消失,将自动恢复.

## 开始

### 安装

最新稳定版本可在 [无](https://www.npmjs.com/package/@featbit/node-server-sdk)。 。 。 .

```bash
npm install --save @featbit/node-server-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/node-server-sdk`。 。 。 .

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

// setup SDK options
const fbClient = new FbClientBuilder()
    .sdkKey("your_sdk_key")
    .streamingUri('ws://localhost:5100')
    .eventsUri("http://localhost:5100")
    .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";
  
  // create a user
  const user = new UserBuilder('a-unique-key-of-user')
    .name('bob')
    .custom('sex', 'female')
    .custom('age', 18)
    .build();

  // evaluate a feature flag for a given user
  const boolVariation = await fbClient.boolVariation(flagKey, user, false);
  console.log(`flag '${flagKey}' returns ${boolVariation} for user ${user.Key}`);

  // evaluate a boolean flag for a given user with evaluation detail
  const boolVariationDetail = await fbClient.boolVariationDetail(flagKey, user, false);
  console.log(`flag '${flagKey}' returns ${boolVariationDetail.value} for user ${user.Key}` +
  `Reason Kind: ${boolVariationDetail.kind}, Reason Description: ${boolVariationDetail.reason}`);

  // make sure the events are flushed before exit
  await fbClient.close();
})();
```

## 实例

-   [控制台应用程序](https://npmcn.com/package/%40featbit/node-server-sdk/examples/console-app)

## SDK 软件

### Fb 客户端

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

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

#### 使用流线的 FbClient

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

const fbClient = new FbClientBuilder()
    .sdkKey("your_sdk_key")
    .streamingUri('ws://localhost:5100')
    .eventsUri("http://localhost:5100")
    .build();
```

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

```javascript
import { FbClientBuilder, DateSyncMode } from "@featbit/node-server-sdk";

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

#### 用户

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

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

如果用户属性缺失或无效,则该属性的条件不匹配,包括否定的运算符,例如 `NotEqual` 财务报告和审定财务报表 `NotOneOf`。通常比较一个已存在的空字符串值。 评估继续沿用后续规则,再由旗下默认规则来进行,如果没有匹配的话.

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

```javascript
import { UserBuilder } from "@featbit/node-server-sdk";

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

或者,可以不使用 `UserBuilder`数字 :

```typescript
import { IUser } from "@featbit/node-server-sdk";

const bob: IUser = {
    key: "unique_key_for_bob",
    name: "Bob",
    customizedProperties: [
        { name: "age", value: "18" },
        { name: "country", value: "FR" },
    ],
};
```

### 评价旗帜

通过使用它已经收到的特性旗数据, SDK **本地计算** 特性旗的值 给定用户.

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

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

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

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

// create a user
const user = new UserBuilder('a-unique-key-of-user')
    .name('bob')
    .custom('sex', 'female')
    .custom('age', 18)
    .build();

// evaluate a feature flag for a given user
const boolVariation = await fbClient.boolVariation(flagKey, user, false);
console.log(`flag '${flagKey}' returns ${boolVariation} for user ${user.Key}`);

// evaluate a boolean flag for a given user with evaluation detail
const boolVariationDetail = await fbClient.boolVariationDetail(flagKey, user, false);
console.log(`flag '${flagKey}' returns ${boolVariationDetail.value} for user ${user.Key}` +
    `Reason Kind: ${boolVariationDetail.kind}, Reason Description: ${boolVariationDetail.reason}`);
```

### 锁定器

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

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

```javascript
const fbClient = new FbClientBuilder()
    .logLevel('debug')
    ...
    .build();

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

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

#### 定义自己的日志

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

```javascript
const logger = new BasicLogger({
    level: 'debug',
    destination: console.log
});

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

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

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

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

### 离线模式

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

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

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

```

> **_注:_** JSON 字符串的填充数据只支持离线模式.

以旗帜和片段表示的数据格式由FeatBit来定义,可能会有变化. 而不是试图 自己构建这些对象, 直接从 FeatBit 服务器以 JSON 格式请求已有的旗帜比较简单 并使用此输出作为文件的起点。 这就是:

```shell
# replace http://localhost:5100 with your evaluation server url
curl -H "Authorization: <your-env-secret>" http://localhost:5100/api/public/sdk/server/latest-all > featbit-bootstrap.json
```

然后使用该文件来初始化 FbClient :

```javascript
import { FbClientBuilder } from "@featbit/node-server-sdk";
import fs from 'fs';

let data: string = '';
try {
  data = fs.readFileSync('path_to_the_json_file', 'utf8');
} catch (err) {
  console.error(err);
}

const fbClient = new FbClientBuilder()
    .offline(false)
    .useJsonBootstrapProvider(data)
    .build();
```

### 禁用事件收藏

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

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

```javascript
import { FbClientBuilder } from "@featbit/node-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(user, eventName, numericValue);
```

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

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

## 支持的 Node.js 版本

这个版本的SDK应该为最近版本的Node.js工作,如果你看到任何带有特定版本的问题, 请创建一个问题.

## 获得支持

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

## 另见

-   [连接到节点.js Sdk](https://docs.featbit.co/getting-started/connect-an-sdk#node.js)

## 常见问题

### @featbit/node-server-sdk 是什么？

https://github\.com/featbit/featbit-node-server-sdk 页面存档备份,存于互联网档案馆

### 如何安装 @featbit/node-server-sdk？

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

### @featbit/node-server-sdk 支持 TypeScript 吗？

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

### @featbit/node-server-sdk 支持 ESM 还是 CommonJS？

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

### @featbit/node-server-sdk 可以商用吗？

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

### @featbit/node-server-sdk 的下载量有多少？

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

### @featbit/node-server-sdk 还在维护吗？

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