# @exodus/feature-flags 中文文档

规范地址：https://npmcn.com/package/%40exodus/feature-flags/

版本：6\.5\.0
npm 元数据更新时间：2026-10-09T17:08:46.444Z
中文译文更新时间：2026-11-14T04:07:21.358Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40exodus/feature-flags
原文对照：https://npmcn.com/package/%40exodus/feature-flags/?lang=original
项目主页：https://github.com/ExodusMovement/exodus/tree/master/libs/features/feature-flags
源码仓库：https://github.com/ExodusMovement/exodus

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

- 包体积（解压后）：41.1 kB，27 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- 首次发布：2023-01-20T17:49:34.847Z
- 最新版本发布：2026-10-09T17:08:46.095Z
- 近 30 天下载量：11241（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 8 个）

## 中文简介

基于远程Config、设备地理定位等的当前可用特性的监测/控制模块

## 安装

```sh
npm install @exodus/feature-flags
```

也可以使用：`pnpm add @exodus/feature-flags`、`yarn add @exodus/feature-flags`、`bun add @exodus/feature-flags`

## README

# @exodus/ feature-flags (英语)

用于监测/控制现有特性的模块和原子 `remoteConfig`,设备 `geolocation`等 (中文(简体) ). 另见 [@ exodus/ feature- control](https://github.com/ExodusMovement/feature-control)。 。 。 .

## 使用量

我们建议您通过 `@exodus/headless`,如下实例所示:

1.  配置时指定您的特性旗 `@exodus/headless` 举个例子.
2.  控制/控制特性标记 :

-   在模块/原子/插件/地物中,使用 `featureFlagAtoms` 依赖性.
-   在UI中:
    -   使用 `selectors.featureFlags.create(featureFlagName)` 要读取当前旗帜值的选择器.
    -   使用 `exodus.featureFlags.enable(featureFlagName)` 财务报告和审定财务报表 `exodus.featureFlags.disable(featureFlagName)` 如果您需要切换运行时的旗帜值.

参见下面的例子代码.

### 背景情况

```js
import createExodus from '@exodus/headless'

const featureFlags = {
  // ... other feature flags,
  dogeMode: {
    localDefaults: {
      // `true` if feature is shipped (available at runtime), `false` otherwise
      available: true,
      // controls whether the feature is enabled by default
      // NOTE: if `available` is false, `enabled` can NOT be true, or you can expect an error
      enabled: true,
    },
    remoteConfig: {
      // path to flag in remote config schema
      path: 'features.dogeMode',
      supportedOverrides: {
        // can be enabled/disabled for all users via remote config
        enabled: true,
        // can be enabled/disabled for users in certain geolocations via remote config
        geolocation: true,
        // can be enabled/disabled for users on certain app versions via remote config
        shutdownSemver: true,
        // can be rolled out to a share of users via remote config, see "Gradual rollout"
        rollout: true,
      },
    },
  },
}

const exodusContainer = createExodus({
  port,
  adapters,
  config: {
    // ...,
    featureFlags,
  },
})

const checkDogeModePlugin = {
  id: 'checkDogeModePlugin',
  factory: ({ featureFlagAtoms }) => {
    const onStart = () => {
      featureFlagAtoms.dogeMode?.get().then(({ isOn }) => {
        console.log('>>> is dogeMode enabled?', isOn)
      })
    }

    return {
      onStart,
    }
  },
  dependencies: ['featureFlagAtoms'],
}

exodusContainer.register({
  definition: checkDogeModePlugin,
})

const exodus = exodusContainer.resolve()
// ... continue as usual
```

### UI 边

```js
import selectors from '~/ui/flux/selectors'

const dogeModeFeatureName = 'dogeMode'

const HomePage = () => {
  const dogeMode = useSelector(selectors.featureFlags.create(dogeModeFeatureName))
  useEffect(() => {
    if (Math.random() < 0.001) {
      exodus.featureFlags.enable(dogeModeFeatureName)
    }
  }, [dogeMode])

  return dogeMode?.isOn ? <DogeMode /> : <NormalMode />
}
```

### 逐步推出

与 `supportedOverrides.rollout`设置 `rollout` 在远程配置中到整数 `0` 改为 `100`数字 :

```json
{ "features": { "dogeMode": { "enabled": true, "rollout": 10 } } }
```

每个用户都从 `0` 改为 `99`数字 : `sha256(featureName + ":" + telemetryId)`,前4个字节,模式100。 水桶还小的时候就挂了 `rollout`因此:

-   用户在增加时会在同一组中停留 `rollout`,并在所有种子相同的设备上.
-   每面旗帜都有独立的群.
-   重新命名的旗帜给新的群体.
-   无效 `rollout` 值会关闭旗帜.
-   旗帜在钱包解锁之前保持本地默认值, 因为 `telemetryId` 来自于种子.

推出需要 `analyticsUserIdAtom` 依赖(来自 `@exodus/analytics`) (中文(简体) ).

### 不使用示例 `@exodus/headless`

见 [实例](https://github.com/ExodusOSS/hydra/tree/master/features/feature-flags/module/__tests__/examples/) 文件夹

## 构成部分

### 远程图形FeatureFlagAtoms

一个原子收藏 `{ [featureName]: atom }`,每个原子都为该特性旗发出当前远程配置值:

```js
{
  isOn: Boolean,
  unavailableStatus: ?String
}
```

### 特性标记原子

一个原子收藏 `{ [featureName]: atom }`,每个原子释放其特征旗帜的当前状态:

```js
{
  isOn: Boolean,
  unavailableStatus: ?String
}
```

### 特性标记原子

以对象映射所有特征标记的当前状态的原子 :

```js
{
  [featureName]: {
    isOn: Boolean,
    unavailableStatus: ?String
  }
}
```

### 特性标记

模块,基于 `remoteConfig` 财务报告和审定财务报表 `geolocation`它将值写入原子 `featureFlagAtoms`,但可能更容易观测到集合特征标记原子 `featureFlagsAtom`。 。 。 .

## 常见问题

### @exodus/feature-flags 是什么？

基于远程Config、设备地理定位等的当前可用特性的监测/控制模块

### 如何安装 @exodus/feature-flags？

在项目目录运行 npm install @exodus/feature-flags，或使用 pnpm add / yarn add / bun add。

### @exodus/feature-flags 支持 TypeScript 吗？

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

### @exodus/feature-flags 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @exodus/feature-flags 可以商用吗？

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

### @exodus/feature-flags 的下载量有多少？

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

### @exodus/feature-flags 还在维护吗？

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