# @flipt-io/flipt-client-js 中文文档

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

版本：0\.7\.0
npm 元数据更新时间：2026-11-08T15:36:33.503Z
中文译文更新时间：2026-11-14T23:23:10.538Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40flipt-io/flipt-client-js
原文对照：https://npmcn.com/package/%40flipt-io/flipt-client-js/?lang=original
项目主页：https://github.com/flipt-io/flipt-client-sdks/tree/main#readme
源码仓库：https://github.com/flipt-io/flipt-client-sdks#main

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

- 包体积（解压后）：2.9 MB，23 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2025-03-29T15:51:53.312Z
- 最新版本发布：2026-11-08T15:36:33.359Z
- 近 30 天下载量：407672（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 7 个）

## 中文简介

为 Web 和 Node.js 翻转客户端评价 SDK

## 安装

```sh
npm install @flipt-io/flipt-client-js
```

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

## README

# 翻转客户端JS

[![flipt-client-js](https://img.shields.io/npm/v/@flipt-io/flipt-client-js?label=%40flipt-io%2Fflipt-client-js)](https://www.npmjs.com/package/@flipt-io/flipt-client-js)

这个 `flipt-client-js` 库中包含用于 Flipt 的 JavaScript/ TypeScript 客户端 [客户端评价](https://www.flipt.io/docs/integration/client) 在 Web 和 Node.js 环境中。 它支持:

-   节点.js
-   浏览器
-   边缘函数(Vercel Edge, Cloudflare 工人等)
-   网络工人

## 安装

> \[注\] 节点.js所建需要节点.js 20或更晚.

```bash
npm install @flipt-io/flipt-client-js
```

## 使用量

```typescript
import { FliptClient } from '@flipt-io/flipt-client-js';

const client = await FliptClient.init({
  namespace: 'default',
  url: 'http://localhost:8080',
  authentication: {
    clientToken: 'secret'
  }
});

const variant = client.evaluateVariant({
  flagKey: 'flag1',
  entityId: 'someentity',
  context: {
    fizz: 'buzz'
  }
});

console.log(variant);
```

### 导入类型

所有类型都可以从主包导出 :

```typescript
import type { Flag, ClientOptions, EvaluationRequest } from '@flipt-io/flipt-client-js';
```

或者,您也可以从专用程序导入类型 `/types` 子路径 :

```typescript
import type { Flag, ClientOptions, EvaluationRequest } from '@flipt-io/flipt-client-js/types';
```

### 初始化参数

这个 `FliptClient` 构造器接受下列可选参数:

-   `options`: 实例 `ClientOptions` 类型,用于支持客户端的若干选项。 其结构是:
    -   `environment`: 评价旗帜时所用的环境(Flipt v2)。 如果不提供,客户端将默认为 `default` 环境.
    -   `namespace`: 获取旗下状态的命名空间 。 如果不提供,客户端将默认为 `default` 名称空间.
    -   `url`: 上游翻转实例的 URL。 如果不提供,客户端将默认为 `http://localhost:8080`。 。 。 .
    -   `updateInterval`数字 : **只有节点.js** 获取新旗帜状态的间隔( 以秒计) 。 如果不提供,客户端将默认为120秒.
    -   `fetchMode`:客户端如何接收旗帜状态更新 : `FetchMode.Polling` (违约)或 `FetchMode.Streaming`。见 [流线](https://npmcn.com/package/%40flipt-io/flipt-client-js/#readme-streaming-server-sent-events)。 。 。 .
    -   `logger`: 一个可选的日志( )`debug`, (中文(简体) ), `info`, (中文(简体) ), `warn`, (中文(简体) ), `error`用于诸如流出事件等诊断. 默认禁用日志 .
    -   `authentication`: 与上游翻转实例通信时使用的认证策略。 如果不提供,客户端将默认为没有认证. 见 [认证](https://npmcn.com/package/%40flipt-io/flipt-client-js/#readme-authentication) 用于提供更多信息.
    -   `reference`编号: [参考文献](https://docs.flipt.io/guides/user/using-references) 用于获取旗帜状态。 如果不提供参考文献,则不使用参考文献.
    -   `snapshot`: 基数64- 编码快照返回 `client.getSnapshot()`提供时 `errorStrategy: ErrorStrategy.Fallback`,客户端可以在下线时初始化,并在网络可用时从Flipt中刷新.
    -   `fetcher`执行 [获取器](https://github.com/flipt-io/flipt-client-sdks/blob/d0869dc9f6b3a65052712926b88fa0f9b18defaa/flipt-client-js/src/core/types.ts#L60-L62) 界面,用于请求旗帜状态时。 如果没有提供,则使用浏览器的默认取取器 [`fetch` API 密码](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) 将被使用.
    -   `errorStrategy`: 获取旗帜状态时所用的错误策略 。 如果不提供,客户端将默认失败. 见 [错误策略](https://npmcn.com/package/%40flipt-io/flipt-client-js/#readme-error-strategies) 用于提供更多信息.
    -   `hook`:用于评价前后回调的钩子执行. 见 [钩子](https://npmcn.com/package/%40flipt-io/flipt-client-js/#readme-hooks) 用于提供更多信息.
    -   `onStateUpdate`:一个没有参数的函数,在客户端应用已更改的旗帜状态后调用. 见 [状态更新听众](https://npmcn.com/package/%40flipt-io/flipt-client-js/#readme-state-update-listeners)。 。 。 .

### 认证

这个 `FliptClient` 支持下列认证战略:

-   无认证( 默认)
-   [客户端托肯认证](https://docs.flipt.io/authentication/using-tokens)
-   [JWT 认证](https://docs.flipt.io/authentication/using-jwts)

### 错误策略

客户 `errorStrategy` 选项支持以下错误策略:

-   `fail`: 如果无法获取旗下状态, 客户端会出错 。 这是默认行为.
-   `fallback`:客户端将保持最后已知的好状态,并在出错时使用该状态进行评价.

### 抓图

客户端支持人工快照旗下状态. 当一个应用程序在Flipt可以到达之前启动时, 这一点是有用的 。 SDK不为您写入本地存储,因为浏览器,Node.js,边缘,以及工人环境存储数据的方式不同.

使用 `getSnapshot()` 将当前状态导出, 保存在您的应用程序所喜欢的地方, 并传回为 `snapshot` 在下一个启动.

```typescript
import { ErrorStrategy, FliptClient } from '@flipt-io/flipt-client-js';

const snapshot = localStorage.getItem('fliptSnapshot') ?? undefined;

const client = await FliptClient.init({
  namespace: 'default',
  url: 'https://your-flipt-instance.com',
  snapshot,
  errorStrategy: ErrorStrategy.Fallback
});

localStorage.setItem('fliptSnapshot', client.getSnapshot());
```

如果Flipt在初始化过程中可以被达到,则新鲜的服务器状态取代所提供的快照. 如果翻转是无法到达的 `ErrorStrategy.Fallback` 设置,客户端使用提供的快照进行评估.

### 自定义获取器

这个 `FliptClient` 支持自定义获取器。 这允许您从自定义源获取旗下状态, 或者覆盖 HTTP 头 .

取取器可以传递给 `FliptClient` 初始化函数 .

```typescript
const client = await FliptClient.init({
  namespace: 'default',
  url: 'http://localhost:8080',
  authentication: {
    clientToken
  },
  fetcher: customFetcher
});
```

获取器是一个需要可选的函数 [`IFetcherOpts`](https://github.com/flipt-io/flipt-client-sdks/blob/d0869dc9f6b3a65052712926b88fa0f9b18defaa/flipt-client-js/src/core/types.ts#L50-L55) 参数并返回 a `Promise` 决心 `Response` 对象.

### 钩子

这个 `FliptClient` 支持允许您在旗帜评价前后执行自定义代码的钩子。 这对伐木、测量采集或其他可观察模式有用.

#### Hook 接口

要使用钩子,请执行 `Hook` 接口.

#### 示例:记录钩

```typescript
import { FliptClient } from '@flipt-io/flipt-client-js';

class LoggingHook {
  before(data: { flagKey: string }) {
    console.log(`Evaluating flag: ${data.flagKey}`);
  }

  after(data: {
    flagKey: string;
    flagType: string;
    value: string;
    reason: string;
    segmentKeys: string[];
  }) {
    console.log(
      `Flag ${data.flagKey} evaluated: type=${data.flagType}, value=${data.value}, reason=${data.reason}`
    );
  }
}

const client = await FliptClient.init({
  namespace: 'default',
  url: 'http://localhost:8080',
  hook: new LoggingHook()
});

const result = client.evaluateVariant({
  flagKey: 'my-flag',
  entityId: 'user-123',
  context: { environment: 'production' }
});

console.log(result);
```

钩子要求所有的评价方法:

-   `evaluateVariant`:每次评价一次
-   `evaluateBoolean`:每次评价一次
-   `evaluateBatch`:在每次请求之前发出一次电话,在每次成功答复之后发出一次电话

**说明:** 虎克是可选的。 如果没有钩子,评价通常不召回.

## 州管理层

这个 `FliptClient` 类从 Flipt 实例中拉出旗帜状态 `url` b. 《公约》 `options` 在即时状态下的对象.

为了更新旗下状态,你可以打电话给 `refresh` 方法 `FliptClient` 课.

> \[注\] 这个 `refresh` 方法返回布尔表示国旗状态是否改变.

```typescript
// Refresh the flag state
let changed = await client.refresh();

if (changed) {
  // Do something
}
```

### 自动更新( 只有节点js)

这个 `FliptClient` 类支持自动刷新旗帜状态.

要自动刷新,你可以通过 `updateInterval` 选项 `FliptClient` 初始化函数 。 盖子下方使用计时器在正常间隔取取取新国旗状态.

> \[注\] 这个 `updateInterval` 选项仅在Node.js环境中得到支持.

```typescript
const client = await FliptClient.init({
  namespace: 'default',
  url: 'http://localhost:8080',
  updateInterval: 30 // refresh every 30 seconds
});
```

一定要打电话给 `close` 方法 `FliptClient` 类,一旦您使用它来停止计时器(或关闭流)并清理资源.

```typescript
client.close();
```

### 流程(服务生活动)

而不是投票,客户端可以实时接收国旗州更新 [服务器事件](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)。当服务器发出变化信号时,客户端会调试旗下状态,而且每一次流重联时,都不会错过更新.

```typescript
import { FliptClient, FetchMode } from '@flipt-io/flipt-client-js';

const client = await FliptClient.init({
  url: 'http://localhost:8080',
  fetchMode: FetchMode.Streaming,
  logger: console // optional
});
```

> \[注\]
> 
> -   在流线模式 `updateInterval` 被忽略,没有开始投票计时.
> -   **浏览器 :** 当地人 `EventSource` 无法发送自定义信头, 因此 `authentication` 不适用于溪流。 使用基于 cookie 的认证或不需要对流端进行认证的 Flipt 服务器 .
> -   **节点.js:** 流线使用 [`eventsource`](https://www.npmjs.com/package/eventsource) 软件包。 认证信头随流请求一同发送 .
> -   `EventSource` 在瞬间出错后自动重新连接。 如果永久关闭连接, 客户端登录出错( 通过 `logger`)并不断为最后已知的旗国服务.

打电话 `close()` 当客户端结束关闭流时.

### 状态更新听众

客户端可以告诉你国旗州变后,这样就可以重新读取所关心的国旗. 要求听众通过自动更新、流线或手册进行修改 `refresh()`。 。 。 .

创建客户端时注册一个收听器 :

```typescript
const client = await FliptClient.init({
  url: 'http://localhost:8080',
  fetchMode: FetchMode.Streaming,
  onStateUpdate: refreshFlags
});
```

或客户端运行时添加并删除听众 :

```typescript
const unsubscribe = client.addStateUpdateListener(refreshFlags);

// Later, to stop listening:
unsubscribe();
```

听众的行为:

-   **只有真正的变化.** 在客户端应用不同于当前状态的旗帜状态后,会调用听众. 未更改的获取和重复的流传信件不称为它,以及 `refresh()` 返回时 `false` 为了他们.
-   **不唤作起初相.** 装入的状态 `init` 不触发一个听众。 注册时读取您需要的旗帜 .
-   **错误不会触发它.** 失败的抓取不调用听众 .
-   **顺序,同步.** 收听者按照被添加的顺序运行,就在新州被应用后. 听众可以评估旗帜、添加或删除听众或打电话 `close()`。 。 。 .
-   **例外情况已记录在案.** 一个听众的例外被记录 `logger.error` 不要阻止别人.
-   **之后什么都没有 `close()`。 。 。 .** 后面没有听众 `close()`。 。 。 .

## ETag 支持

默认取取器使用 [Etag HTTP 标题](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) 以减少向 Flipt 实例提出的请求数量。 在旗下状态不经常更新且您想要减少服务器上负载的情景中,这很有用.

要禁用ETag 支持, 您可以执行 [自定义获取器](https://npmcn.com/package/%40flipt-io/flipt-client-js/#readme-custom-fetcher) 不使用ETags.

## Slim 模块

这个 `slim` 模块是针对高级或非标准环境设计的,其中您需要完全控制WASM 二进制的加载方式。 与试图自动加载WASM文件的默认客户端不同,瘦客户端要求您明确提供WASM文件(作为URL,缓冲等).

**为什么要用瘦模组?**

-   **边缘/无服务/海关环境:** 一些平台(如Cloudflare Workers,Vercel Edge,或某些节点.js设置)限制文件被加载或捆绑的方式. 瘦客户端允许您以适合您环境的方式加载WASM文件.
-   **全控 :** 您决定 WASM 文件的加载方式和时间 — 从 CDN 拖放、 从磁盘加载或使用自定义加载器 .
-   **兼容性 :** 瘦客户端去除了WASM加载的所有假设,使其与任何可以提供WASM二进制的环境相兼容.
-   **套装大小 :** 微弱的构造可能排除了与WASM加载相关的一些代码,使得它更轻而易举,更能为某些用法所动摇.

如果您正在使用带有捆绑器的标准浏览器应用程序,默认客户端通常更容易. 对于边缘,没有服务器,或自定义设置,瘦客户端是合适的工具.

### 使用 `@flipt-io/flipt-client-js/slim` 模块

这个 `slim` fliptClient的构建是为您想要提供自己的WASM 二进制的环境而设计的,比如现代浏览器(带有捆绑器)或Node.js.

#### 浏览器用法( 带有类似 Vite, Webpack等的 Bundler)

1.  **导入并初始化客户端 :**
    
    ```ts
    import { FliptClient } from '@flipt-io/flipt-client-js/slim';
    import wasmUrl from '@flipt-io/flipt-client-js/engine.wasm';
    
    async function main() {
      const client = await FliptClient.init(
        {
          namespace: 'default',
          url: 'http://localhost:8080'
        },
        { wasm: wasmUrl }
      );
    
      // Use the client as normal
      const result = client.evaluateBoolean({
        flagKey: 'my-flag',
        entityId: 'user-123',
        context: { country: 'US' }
      });
    
      console.log(result);
    }
    
    main();
    ```
    
2.  **确保您的捆绑器配置为处理 `.wasm` 文档.**
    
    -   对于Vite,这个工作出了盒子.
    -   对于Webpack,您可能需要添加一条规则: `.wasm` 文档.

* * *

#### 节点使用

1.  **导入并初始化客户端 :**
    
    ```ts
    import { FliptClient } from '@flipt-io/flipt-client-js/slim';
    import { readFileSync } from 'fs';
    import path from 'path';
    import { fileURLToPath } from 'url';
    
    // Resolve the path to the WASM file
    const __filename = fileURLToPath(import.meta.url);
    const __dirname = path.dirname(__filename);
    const wasmPath = path.join(
      __dirname,
      '../node_modules/@flipt-io/flipt-client-js/engine.wasm'
    );
    const wasmBuffer = readFileSync(wasmPath);
    
    async function main() {
      const client = await FliptClient.init(
        {
          namespace: 'default',
          url: 'http://localhost:8080'
        },
        { wasm: wasmBuffer }
      );
    
      // Use the client as normal
      const result = client.evaluateBoolean({
        flagKey: 'my-flag',
        entityId: 'user-123',
        context: { country: 'US' }
      });
    
      console.log(result);
    }
    
    main();
    ```
    
    -   **说明:** 在Node.js中,您必须使用 WASM 文件作为缓冲器加载 `fs.readFileSync`。 。 。 .
2.  **用一个支持无害环境管理和顶级等待的加载器运行您的脚本, 例如 `ts-node` 或者说 `tsx`数字 :**
    
    ```sh
    npx tsx src/index.ts
    ```
    

* * *

### 补充说明

-   这个 `slim` 构建需要您通过 `wasm` 选项.
-   对于浏览器的使用,将 URL 传递到 WASM 文件(使用您捆绑器的资产处理) .
-   对于Node.js,通过WASM文件作为缓冲.
-   确保您的环境支持顶级 `await` 或将代码包入同步函数中.

## 发展

### 刚才

这个库使用WebAssem(WASM)层与Flipt服务器交互. 它用 Rust 写成,并使用 `wasm-bindgen` 财务报告和审定财务报表 `wasm-pack` 工具。 我们用JavaScript API将已建成的WASM层包裹起来,以便于在网络环境中使用.

### 先决条件

-   [转动引擎 转动引擎](https://npmcn.com/package/%40flipt-io/flipt-engine-wasm-js)

### 构建

```bash
npm run build
```

### 测试

```bash
npm install
npm test
```

## 捐款

欢迎捐款! 请随意打开一个问题或提交拉出请求.

## 许可证

本项目根据以下规定获得许可证: [MIT 许可证](https://npmcn.com/package/%40flipt-io/flipt-client-js/LICENSE)。 。 。 .

## 常见问题

### @flipt-io/flipt-client-js 是什么？

为 Web 和 Node\.js 翻转客户端评价 SDK

### 如何安装 @flipt-io/flipt-client-js？

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

### @flipt-io/flipt-client-js 支持 TypeScript 吗？

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

### @flipt-io/flipt-client-js 支持 ESM 还是 CommonJS？

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

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

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

### @flipt-io/flipt-client-js 可以商用吗？

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

### @flipt-io/flipt-client-js 的下载量有多少？

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

### @flipt-io/flipt-client-js 还在维护吗？

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