# @harnessio/ff-javascript-client-sdk 中文文档

规范地址：https://npmcn.com/package/%40harnessio/ff-javascript-client-sdk/

版本：1\.32\.0
npm 元数据更新时间：2026-11-16T17:37:05.657Z
中文译文更新时间：2026-11-17T10:13:27.788Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40harnessio/ff-javascript-client-sdk
原文对照：https://npmcn.com/package/%40harnessio/ff-javascript-client-sdk/?lang=original
项目主页：https://github.com/harness/ff-javascript-client-sdk#readme
源码仓库：https://github.com/harness/ff-javascript-client-sdk

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

- 包体积（解压后）：115 kB，15 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2021-03-10T10:24:51.599Z
- 最新版本发布：2025-12-23T15:12:51.603Z
- 近 30 天下载量：136775（2026-10-18 至 2026-11-16，npm 官方下载统计）
- 已发布版本数：128（近 12 个月 2 个）

## 中文简介

基本库用于将CF整合到javascript应用中.

## 安装

```sh
npm install @harnessio/ff-javascript-client-sdk
```

也可以使用：`pnpm add @harnessio/ff-javascript-client-sdk`、`yarn add @harnessio/ff-javascript-client-sdk`、`bun add @harnessio/ff-javascript-client-sdk`

## README

# 在你开始之前

Harness Feature Flags(FF)是一个功能管理解决方案,使用户能够改变软件的功能, 没有部署新的代码。 FF使用地标来隐藏代码或行为,而不必运送新的版本 软件。 特征旗帜就像一个强大的如果语句.

更多信息见 [https://harness.io/products/feature-flags/ (中文(中国大陆) )](https://harness.io/products/feature-flags/)

更多信息,见 [https://developer.harness.io/docs/feature-flags/ 页面存档备份,存于互联网档案馆](https://developer.harness.io/docs/feature-flags/)

报名,https://app.harness.io/auth/#/signup/

npm发布页面,见https://www.npmjs.com/package/@harnesio/ff-javascript-client-sdk

# 用于 JavaScript 的 Harness 特性旗客户端 SDK

用于将Harness Feature Flags整合到JavaScript UI应用程序的库.

## 安装

```shell
npm i @harnessio/ff-javascript-client-sdk
```

或者说

```shell
yarn add @harnessio/ff-javascript-client-sdk
```

## 使用量

```typescript
import { initialize, Event } from '@harnessio/ff-javascript-client-sdk'
```

初始化 SDK 有 api 密钥和目标信息 .

```typescript
initialize(FeatureFlagSDKKey: string, target: Target, options?: Options)
```

其中 `Target` 财务报告和审定财务报表 `Options` 定义如下:

```typescript
interface Target {
  identifier: string
  name?: string
  anonymous?: boolean
  attributes?: object
}

interface Options {
  baseUrl?: string
  eventUrl?: string
  eventsSyncInterval?: number
  pollingInterval?: number
  pollingEnabled?: boolean
  streamEnabled?: boolean
  debug?: boolean,
  cache?: boolean | CacheOptions
  logger?: Logger
  maxStreamRetries?: number
  enableAnalytics?: boolean
}
```

例如:

```typescript
const client = initialize('00000000-1111-2222-3333-444444444444', {
  identifier: YOUR_TARGET_IDENTIFIER,      // Target identifier
  name: YOUR_TARGET_NAME,                  // Optional target name
  attributes: {                            // Optional target attributes
    email: 'sample@sample.com'
  }
})
```

## 流和投票模式

默认情况下,Harness Flags SDK已启用流线并启用投票. 两种模式都可以根据您使用SDK配置的偏好进行切换.

### 流线模式

流线模式在您的应用程序和地物旗舰服务之间建立连续连接. 这使得可以实时更新地标而无需定期检查. 如果在流出时发生错误 `pollingEnabled` 设置为 `true`, (中文(简体) ), sDK会自动倒回投票模式,直到可以重新建立流. 若为 `pollingEnabled` 实值 `false`{\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}溪流会试图重新连接 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}而不会回到民调.

### 投票模式

在投票模式下,SDK会定期与地物旗服务进行查询,以获取地物旗的更新. 这些检查的频率可以使用SDK的配置来调整.

### 不流出或投票

如果流线和投票模式都被禁止(`streamEnabled: false` 财务报告和审定财务报表 `pollingEnabled: false`, (中文(简体) ), sDK 将不会在初始获取后自动获取特性旗更新 . 这意味着在初始负载后,哈内斯服务器上对功能旗进行的任何更改,在SDK重新被初始化或其中一个模式被重新启用之前,都不会被反映在应用程序中.

在您想要确保一组一致的特征标记的特定情况下,此配置可能有用 用于一个会话或应用程序在不需要定期更新的环境中运行。 然而,必须意识到,如果在服务器上改变旗帜,这种配置会导致过时的旗帜评价.

要配置模式 :

```typescript

const options = {
  streamEnabled: true, // Enable or disable streaming - default is enabled
  pollingEnabled: true, // Enable or disable polling - default is enabled if stream enabled, or disabled if stream disabled.
  pollingInterval: 60000, // Polling interval in ms, default is 60000ms which is the minimum. If set below this, will default to 60000ms.
}

const client = initialize(
  'YOUR_SDK_KEY',
  {
    identifier: 'Harness1',
    attributes: {
      lastUpdated: Date(),
      host: location.href
    }
  },
  options
)
```

### 最大流调试

在SDK停止尝试重新连接或回归投票(如果启用)前,您可以配置流式重试的最大次数. 最大重试选项可以设定为任意正数或无限重试(即默认).

```typescript
const options = {
  maxRetries: 5, // Set the maximum number of retries for streaming. Default is Infinity.
  streamEnabled: true,
  pollingEnabled: true,
  pollingInterval: 60000,
}

const client = initialize(
    'YOUR_SDK_KEY',
    {
      identifier: 'Harness1',
      attributes: {
        lastUpdated: Date(),
        host: location.href
      }
    },
    options
)

```

如果达到最大要求,且投票结果属实,则SDK将保持投票模式。 如果投票Enabled是虚假的,SDK不会进行民意调查,在SDK客户端再次被初始化之前,评价不会被更新,例如应用程序或页面被重新启动.

## 听从事件 `client` 举个例子.

```typescript
client.on(Event.READY, flags => {
  // Event happens when connection to server is established
  // flags contains all evaluations against SDK key
})

client.on(Event.FLAGS_LOADED, evaluations => {
  // Event happens when flags are loaded from the server
})

client.on(Event.CACHE_LOADED, evaluations => {
  // Event happens when flags are loaded from the cache
})

client.on(Event.CHANGED, flagInfo => {
  // Event happens when a changed event is pushed
  // flagInfo contains the updated feature flag
})

client.on(Event.DISCONNECTED, () => {
  // Event happens when connection is disconnected
})

client.on(Event.CONNECTED, () => {
  // Event happens when connection has been lost and reestablished
})

client.on(Event.POLLING, () => {
  // Event happens when polling begins
})

client.on(Event.POLLING_STOPPED, () => {
  // Event happens when polling stops
})

client.on(Event.ERROR, error => {
  // Event happens when connection some error has occurred
})

client.on(Event.ERROR_CACHE, error => {
  // Event happens when an error occurs when accessing the cache
})

client.on(Event.ERROR_AUTH, error => {
  // Event happens when unable to authenticate
})

client.on(Event.ERROR_FETCH_FLAGS, error => {
  // Event happens when unable to fetch flags from the service
})

client.on(Event.ERROR_FETCH_FLAG, error => {
  // Event happens when unable to fetch an individual flag from the service
})

client.on(Event.ERROR_METRICS, error => {
  // Event happens when unable to report metrics back to the service
})

client.on(Event.ERROR_STREAM, error => {
  // Event happens when the stream returns an error
})
```

### 获取特定特性旗的值

如果您想知道默认变量是在获得值时被返回的, 例如, 如果在缓存中找不到提供的旗帜, 那么与 Debug 的第三个参数会通过真实 :

```typescript
const result = client.variation('Dark_Theme', false, true);
```

何时 `withDebug` ,结果对象将具有以下结构:

```typescript
interface VariationValueWithDebug {
  value: any,                 // The actual variation value
  isDefaultValue: boolean     // True if the default variation was returned, false otherwise
}
```

例如,如果找不到旗帜标识符“ Dark Theme ” , 结果会像 :

```typescript
{
  value: false,
  isDefaultValue: true
}
```

如果您不需要知道默认变量被返回:

```typescript
const variationValue = client.variation('Dark_Theme', false) // second argument is default value when variation does not exist
```

在这种情况下,结果将是一个直接值,要么来自现有的变量,要么来自您提供的默认值。 不会有一个对象结构;你只需得到这个值本身.

例如:

-   如果旗下标识符“ Dark Theme” 存在于存储中, 变化 价值将是该标识符的存储值.
-   如果旗帜标识符“ Dark Theme” 不存在, 变化 值将是此处提供的默认值

-   注意返回默认变量的原因可以是:
    1.  SDK 尚未初始化
    2.  旗帜标识符中的 Typo
    3.  使用错误的工程 API 密钥

#### 听着 `ERROR_DEFAULT_VARIATION_RETURNED` 事件

你们也可以听 `ERROR_DEFAULT_VARIATION_RETURNED` 事件,当返回默认变量时会释放,因为缓存中找不到旗帜。 这对于在找不到一面旗帜时进行伐木或采取其他行动是有用的.

活动监听实例:

```typescript
client.on(Event.ERROR_DEFAULT_VARIATION_RETURNED, ({ flag, defaultVariation }) => {
  console.warn(`Default variation returned for flag: ${flag}, value: ${defaultVariation}`)
})
```

### 清理

删除事件的听众 `client.off`。 。 。 .

```typescript
client.off(Event.ERROR, error => {
  // Do something when an error occurs
})
```

删除所有听众 :

```typescript
client.off()
```

关闭您的申请时, 请打电话 `client.close()` 关闭事件流.

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

## 缓存

在实际操作中,旗帜很少改变,因此可以缓存从服务器收到的最后评价,以便 您需要尽快启动申请。 设置 `cache` 选项为 `true` 或作为一个对象(参见界面) (见下文)将允许SDK将其评价储存到 `localStorage` 启动时检索。 这让SDK得到 即刻启动并开始为旗帜服务,同时进行认证和获取最新评价 从幕后服务器.

```typescript
const client = initialize('00000000-1111-2222-3333-444444444444', {
    identifier: YOUR_TARGET_IDENTIFIER,
    name: YOUR_TARGET_NAME
  }, {
    cache: true // enable caching
  }
)
```

这个 `cache` 选项也可以作为对象通过,其选项如下.

```typescript
interface CacheOptions {
  // maximum age of stored cache, in ms, before it is considered stale
  ttl?: number
  // storage mechanism to use, conforming to the Web Storage API standard, can be either synchronous or asynchronous
  // defaults to localStorage
  storage?: AsyncStorage | SyncStorage
  /**
   * use target attributes when deriving the cache key
   * when set to `false` or omitted, the key will be formed using only the target identifier and SDK key
   * when set to `true`, all target attributes with be used in addition to the target identifier and SDK key
   * can be set to an array of target attributes to use a subset in addition to the target identifier and SDK key
   * defaults to false
   */
  deriveKeyFromTargetAttributes?: boolean | string[]
}
```

## 设定评价

在某些情况下,也许值得向SDK提供一套评价,然后可以立即提供。 你个 当您需要时, 可能会考虑这一点:

-   **缩短应用程序启动时间** 通过提供默认值或评价快照。 比如说,如果你 应用程序是服务器侧生成的,然后在服务器上检索评价并提供评价可能有意义 在要注入 SDK 页面的 HTML 中
-   **提供网络冗余** 通过允许您的应用程序检测访问服务的网络连接问题 从其他来源装入评价

为了达到这个目的,你可以叫 `setEvaluations` 初始化客户端后的任何时间。 这个 `setEvaluations` 方法需要数组 `Evaluation` 对象作为参数.

```typescript
client.setEvaluations(evals);
```

其中 `Evaluation` 定义如下:

```typescript
interface Evaluation {
  flag: string // Feature flag identifier
  identifier: string // variation identifier
  value: boolean | string | number | object | undefined // variation value
  kind: string // boolean | json | string | int
  deleted?: boolean // mark that feature flag is deleted
}
```

## 认证请求超时

这个 `authRequestReadTimeout` 选项允许您为认证请求指定以毫秒计的超时。 如果请求需要比本次超时更长的时间,则会中止. 这对于防止因网络问题或反应迟缓而出现挂起请求是有用的.

如果由于这个超时而中止请求, SDK 将无法初始化 `ERROR_AUTH` 财务报告和审定财务报表 `ERROR` 将释放事件.

如果没有指定默认值为 `0` 这意味着不会出现超时.

\*\* 这仅适用于认证请求。 如果您想对 SDK 提出的其余请求设定读取超时, 您可以注册 [API 中间软件](https://npmcn.com/package/%40harnessio/ff-javascript-client-sdk/#readme-api-middleware)

```typescript
const options = {
  authRequestReadTimeout: 30000, // Timeout in milliseconds (default: 0 - no timeout)
};

const client = initialize(
  'YOUR_API_KEY',
  {
    identifier: 'Harness1',
    attributes: {
      lastUpdated: Date(),
      host: location.href,
    },
  },
  options
);
```

## API 中间软件

这个 `registerAPIRequestMiddleware` 函数允许您注册一个中间软件功能来操纵API请求的有效载荷(URL,正文和头).

```typescript
function abortControllerMiddleware([url, options]) {
  if (window.AbortController) {
    const abortController = new AbortController();
    options.signal = abortController.signal;

    // Set a timeout to automatically abort the request after 30 seconds
    setTimeout(() => abortController.abort(), 30000);
  }

  return [url, options]; // Return the modified or original arguments
}

// Register the middleware
client.registerAPIRequestMiddleware(abortControllerMiddleware);
```

此示例中间软件会自动给每个请求附加一个中止控制器, 如果请求需要比指定的超时时间长, 则会中止请求 。 也可以自定义中间软件来进行其他动作,例如记录或修改标题.

## 日志

默认情况下, Javascript客户端 SDK 将使用 `console` 对象。 在某些情况下,它 可用于登录某项服务,或者在没有记录错误的情况下静默地失败.

```typescript
const myLogger = {
  debug: (...data) => {
    // do something with the logged debug message
  },
  info: (...data) => {
    // do something with the logged info message
  },
  error: (...data) => {
    // do something with the logged error message
  },
  warn: (...data) => {
    // do something with the logged warning message
  }
}

const client = initialize(
  '00000000-1111-2222-3333-444444444444',
  {
    identifier: YOUR_TARGET_IDENTIFIER,
    name: YOUR_TARGET_NAME
  },
  {
    logger: myLogger // override logger
  }
)
```

## 从 unpkg 直接导入

如果您想直接导入此库( 无需使用 npm 或 rarn) :

```html
<script type="module">
  import { initialize, Event } from 'https://unpkg.com/@harnessio/ff-javascript-client-sdk/dist/sdk.client.js'
</script>
```

如果您需要支持不支持 ES 模块的旧浏览器:

```html
<script src="https://unpkg.com/@harnessio/ff-javascript-client-sdk/dist/sdk.client-iife.js"></script>
<script>
  var initialize = HarnessFFSDK.initialize
  var Event = HarnessFFSDK.Event
</script>
```

## 进一步阅读

[与移动设备网页视图整合](https://npmcn.com/package/%40harnessio/ff-javascript-client-sdk/mobile_device_support.md)

## 许可证

Apache 第2版 (英语).

## 常见问题

### @harnessio/ff-javascript-client-sdk 是什么？

基本库用于将CF整合到javascript应用中\.

### 如何安装 @harnessio/ff-javascript-client-sdk？

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

### @harnessio/ff-javascript-client-sdk 支持 TypeScript 吗？

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

### @harnessio/ff-javascript-client-sdk 支持 ESM 还是 CommonJS？

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

### @harnessio/ff-javascript-client-sdk 可以商用吗？

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

### @harnessio/ff-javascript-client-sdk 的下载量有多少？

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

### @harnessio/ff-javascript-client-sdk 还在维护吗？

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

