# @featureflip/browser 中文文档

规范地址：https://npmcn.com/package/%40featureflip/browser/

版本：2\.19\.1
npm 元数据更新时间：2026-11-09T16:14:09.920Z
中文译文更新时间：2026-11-14T13:01:20.992Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40featureflip/browser
原文对照：https://npmcn.com/package/%40featureflip/browser/?lang=original
项目主页：https://featureflip.io/docs/sdks/browser/
源码仓库：https://github.com/canopy-labs/featureflip-browser

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

- 包体积（解压后）：69.8 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19\.0
- 运行依赖：0 个
- 首次发布：2026-04-02T04:59:44.565Z
- 最新版本发布：2026-11-09T16:14:09.657Z
- 近 30 天下载量：3059（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 33 个）

## 中文简介

Featureflip 浏览器 SDK - 框架- 不可知特性旗客户端

## 安装

```sh
npm install @featureflip/browser
```

也可以使用：`pnpm add @featureflip/browser`、`yarn add @featureflip/browser`、`bun add @featureflip/browser`

## README

# @ featureflip/ 浏览器

用于评价的框架不可知浏览器 SDK [特性flip](https://featureflip.io/) 特征标记.

## 安装

```bash
npm install @featureflip/browser
```

## 快速启动

```ts
import { FeatureflipClient } from '@featureflip/browser';

const client = FeatureflipClient.get({
  clientKey: 'your-client-sdk-key',
});

await client.initialize();

const showBanner = client.boolVariation('show-banner', false);
```

> **单通由建筑.** `FeatureflipClient.get()` 是获得客户的唯一方法——在v2.0中公共建筑师被移除. 通话 `get()` 不止一次都一样 `clientKey` 返回控件指向一个共享的下方客户端(重新计算)。 这使得框架绑定,React BureauMode双高架,每个组件构造都无害——它们都决心每个键一个SSE连接和一个旗下商店.

## API 参考

### `FeatureflipClient.get(config)`

```ts
FeatureflipClient.get(config: FeatureflipClientConfig): FeatureflipClient
```

返回给定客户端密钥的客户端 。 第一个呼叫构建并注册一个共享核心;随后使用同一密钥的呼叫返回一个指向缓存核心的新手柄. 当一个密钥的最后一个手柄被关闭后,核心会关闭并被从缓存中取出.

### 配置选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `clientKey` | `string` | **(必须)** | 来自您的工程设置的客户端 SDK 密钥 |
| `baseUrl` | `string` | `https://eval.featureflip.io` | 评价 API 基础 URL |
| `context` | `Record<string, unknown>` | `{}` | 初步评价背景(用户属性) |
| `streaming` | `boolean` | `true` | 为实时更新启用 SSE 流线 |
| `initTimeout` | `number` | `10000` | 初始评估请求超时( 以毫秒计) |
| `bootstrap` | `Record<string, unknown> | 'localStorage'` | `undefined` | 在服务器首个响应前服务值 。 见 [启动](https://npmcn.com/package/%40featureflip/browser/#readme-bootstrapping)。 。 。 . |
| `sendEvaluationEvents` | `boolean` | `true` | 报告您的应用程序所读的标记 。 Featureflip 使用这个来告诉一面旗帜, 您的代码仍然从它只发送的一面读取, 这就是让一个未使用的客户端的旗帜存档的原因 。 只读取 `flagDetail()` 键 `*Variation` 方法数。 设定 `false` 无法报告 —— 特性flip 然后将它发给这个客户端的每面旗帜视为在使用中 . |

### 方法

#### `initialize(options?: { waitForServer?: boolean }): Promise<void>`

从服务器获取全部旗下值。 在读取变量前必须先调用( 除非客户端被拖出) 。 如果 `streaming` 已启用。 带有拖曳值, 当获取在背景中运行时立即解析; 通过 `{ waitForServer: true }` 以等待第一个服务器响应.

#### `flagSource: 'none' | 'bootstrap' | 'localStorage' | 'server'`

目前服务的价值来自何处.

#### `boolVariation(key: string, defaultValue: boolean): boolean`

返回布尔旗值,或 `defaultValue` 如果国旗缺失或没有布尔.

#### `stringVariation(key: string, defaultValue: string): string`

返回字符串旗帜值,或 `defaultValue` 如果国旗缺少或没有字符串.

#### `numberVariation(key: string, defaultValue: number): number`

返回数字标记值,或 `defaultValue` 如果国旗缺少或没有数字.

#### `jsonVariation<T>(key: string, defaultValue: T): T`

返回所投放的旗帜值 `T`,或 `defaultValue` 如果国旗不见了.

#### `identify(context: Record<string, unknown>): Promise<void>`

重新评价所有带有新上下文的旗帜(如登录后). 输出 `change` 用于任何价值观发生变化的旗帜的事件.

```ts
await client.identify({ user_id: '123', plan: 'pro' });
```

#### `on(event: EventType, handler: EventHandler): void`

订阅事件.

-   `'ready'` -- 开出一次, 当客户端首次有值需要服务时( 收到) `{ source }`,数值与 `flagSource`(中文(简体) )
-   `'change'` -- 当旗帜值改变时被发射(收到a) `FlagChanges` 对象)
-   `'error'` -- 在流出或网络出错时开火

```ts
client.on('change', (changes) => {
  console.log('Flags changed:', changes);
});
```

#### `off(event: EventType, handler: EventHandler): void`

不订阅事件.

#### `close(): void`

减少对共享核心的重计。 当给定客户端密钥的最后一个手柄被关闭后,共享核心会关闭SSE连接并自去除工厂缓存. 在同一把把柄上的双关是无线的.

### 启动

过 `bootstrap` 所以第一个颜料不会在网络上等待:

-   **一个对象** 联 合 国 `{ flagKey: value }`,通常由服务器 SDK 在渲染页面并嵌入到 HTML 中时进行评估。 客户端立即初始化,并在您第一次阅读前不提出任何请求.
-   **`'localStorage'`**:客户端保存它收到的每个客户端密钥和上下文的值(由散列所命名的五个最近上下文不存储),并在下一个页面负载上为它们服务. 对一种语境的价值观从不为另一种语境服务。 服务器 SDK 密钥被忽略 .

无论哪种方式,客户端仍然像往常一样取来和流出. 服务器的值替换了靴子并释放 `change` 对于任何不同的.

```ts
const client = FeatureflipClient.get({
  clientKey: 'your-client-sdk-key',
  context: window.__FLAG_CONTEXT__, // the same context the server evaluated with
  bootstrap: window.__FLAGS__,
});
```

对于服务器侧渲染, `FeatureflipClient.forServerRender(config)` 返回服务客户端 `bootstrap` 对象的值,不提出网络请求,也不被缓存,因此对不同用户同时提出的请求从不共享.

全向导 : [Bootstrap 客户端旗帜](https://featureflip.io/docs/guides/bootstrap/)。 。 。 .

### 测试

使用 `FeatureflipClient.forTesting()` 创建具有预定旗帜值的客户端 -- -- 没有网络呼叫.

```ts
const client = FeatureflipClient.forTesting({
  'show-banner': true,
  'button-color': 'blue',
});

client.boolVariation('show-banner', false); // true
client.stringVariation('button-color', 'red'); // 'blue'
```

## 许可证

阿帕奇 - 2.0

## 常见问题

### @featureflip/browser 是什么？

Featureflip 浏览器 SDK - 框架- 不可知特性旗客户端

### 如何安装 @featureflip/browser？

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

### @featureflip/browser 支持 TypeScript 吗？

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

### @featureflip/browser 支持 ESM 还是 CommonJS？

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

### @featureflip/browser 需要什么版本的 Node\.js？

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

### @featureflip/browser 可以商用吗？

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

### @featureflip/browser 的下载量有多少？

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

### @featureflip/browser 还在维护吗？

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