React 功能标志（feature-flags）完整指南：配置、测试与调试实战

feature-flags by facebook/react

697 周安装量

244,300 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/facebook/react --skill feature-flags

开发 JavaScript 框架测试

🇨🇳中文介绍

React 功能标志

标志文件

文件	用途
`packages/shared/ReactFeatureFlags.js`	默认标志（canary 版本），`__EXPERIMENTAL__` 覆盖
`packages/shared/forks/ReactFeatureFlags.www.js`	www 渠道，`__VARIANT__` 覆盖
`packages/shared/forks/ReactFeatureFlags.native-fb.js`	React Native，`__VARIANT__` 覆盖

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

`@gate` 编译指示（测试级别）

当功能在没有标志的情况下完全不可用时使用：

// @gate enableViewTransition
it('supports view transitions', () => {
  // 此测试仅在 enableViewTransition 为 true 时运行
  // 当为 false 时会被跳过（而非失败）
});

`gate()` 内联（断言级别）

当功能存在但行为根据标志不同时使用：

it('renders component', async () => {
  await act(() => root.render(<App />));

  if (gate(flags => flags.enableNewBehavior)) {
    expect(container.textContent).toBe('new output');
  } else {
    expect(container.textContent).toBe('legacy output');
  }
});

添加到 ReactFeatureFlags.js 并设置默认值
添加到每个分支文件（*.www.js、*.native-fb.js 等）
如果应在 www/RN 中变化，则在分支文件中设置为 __VARIANT__
使用 @gate flagName 或内联 gate() 进行门控测试

使用 /flags 查看各渠道的状态。完整命令选项请参阅 flags 技能。

`VARIANT` 标志（GKs）

设置为 __VARIANT__ 的标志模拟守门员 - 会测试两次（true 和 false）：

/test www <pattern>              # __VARIANT__ = true
/test www variant false <pattern> # __VARIANT__ = false

调试渠道特定故障

运行 /flags --diff <channel1> <channel2> 比较值
检查 @gate 条件 - 测试可能被门控到特定渠道
运行 /test <channel> <pattern> 以隔离故障
如果新添加标志，请验证其是否存在于所有分支文件中

忘记两种变体 - 对于 __VARIANT__ 标志，始终测试 www 和 www variant false
对行为差异使用 @gate - 如果两条路径都应运行，请使用内联 gate()
缺少分支文件 - 新标志必须添加到所有分支文件，而不仅仅是主文件
错误的门控语法 - 正确语法是 gate(flags => flags.name)，而不是 gate('name')

🇺🇸English

React Feature Flags

Flag Files

File	Purpose
`packages/shared/ReactFeatureFlags.js`	Default flags (canary), `__EXPERIMENTAL__` overrides
`packages/shared/forks/ReactFeatureFlags.www.js`	www channel, `__VARIANT__` overrides
`packages/shared/forks/ReactFeatureFlags.native-fb.js`	React Native, `__VARIANT__` overrides
`packages/shared/forks/ReactFeatureFlags.test-renderer.js`	Test renderer

Gating Tests

`@gate` pragma (test-level)

Use when the feature is completely unavailable without the flag:

// @gate enableViewTransition
it('supports view transitions', () => {
  // This test only runs when enableViewTransition is true
  // and is SKIPPED (not failed) when false
});

`gate()` inline (assertion-level)

Use when the feature exists but behavior differs based on flag:

it('renders component', async () => {
  await act(() => root.render(<App />));

  if (gate(flags => flags.enableNewBehavior)) {
    expect(container.textContent).toBe('new output');
  } else {
    expect(container.textContent).toBe('legacy output');
  }
});

Adding a New Flag

Add to ReactFeatureFlags.js with default value
Add to each fork file (*.www.js, *.native-fb.js, etc.)
If it should vary in www/RN, set to __VARIANT__ in the fork file
Gate tests with @gate flagName or inline gate()

Checking Flag States

Use /flags to view states across channels. See the flags skill for full command options.

`VARIANT` Flags (GKs)

Flags set to __VARIANT__ simulate gatekeepers - tested twice (true and false):

/test www <pattern>              # __VARIANT__ = true
/test www variant false <pattern> # __VARIANT__ = false

Debugging Channel-Specific Failures

Run /flags --diff <channel1> <channel2> to compare values
Check @gate conditions - test may be gated to specific channels
Run /test <channel> <pattern> to isolate the failure
Verify flag exists in all fork files if newly added

Common Mistakes

Forgetting both variants - Always test www AND www variant false for __VARIANT__ flags
Using @gate for behavior differences - Use inline gate() if both paths should run
Missing fork files - New flags must be added to ALL fork files, not just the main one
Wrong gate syntax - It's gate(flags => flags.name), not gate('name')

Weekly Installs

659

Repository

facebook/react

GitHub Stars

244.1K

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode541

codex525

gemini-cli522

github-copilot473

claude-code429

amp420

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

106,200 周安装

React 功能标志（feature-flags）完整指南：配置、测试与调试实战

🇨🇳中文介绍

React 功能标志

标志文件

相关 Skills

门控测试

`@gate` 编译指示（测试级别）

`gate()` 内联（断言级别）

添加新标志

检查标志状态

`VARIANT` 标志（GKs）

调试渠道特定故障

常见错误

🇺🇸English

React Feature Flags

Flag Files

Gating Tests

`@gate` pragma (test-level)

`gate()` inline (assertion-level)

Adding a New Flag

Checking Flag States

`VARIANT` Flags (GKs)

Debugging Channel-Specific Failures

Common Mistakes

最新 Skills

React 功能标志（feature-flags）完整指南：配置、测试与调试实战

🇨🇳中文介绍

React 功能标志

标志文件

相关 Skills

门控测试

@gate 编译指示（测试级别）

gate() 内联（断言级别）

添加新标志

检查标志状态

__VARIANT__ 标志（GKs）

调试渠道特定故障

常见错误

🇺🇸English

React Feature Flags

Flag Files

Gating Tests

@gate pragma (test-level)

gate() inline (assertion-level)

Adding a New Flag

Checking Flag States

__VARIANT__ Flags (GKs)

Debugging Channel-Specific Failures

Common Mistakes

最新 Skills

`@gate` 编译指示（测试级别）

`gate()` 内联（断言级别）

`VARIANT` 标志（GKs）

`@gate` pragma (test-level)

`gate()` inline (assertion-level)

`VARIANT` Flags (GKs)