React Compiler 指令是特殊的字符串字面量，用于控制是否编译特定函数。

¥React Compiler directives are special string literals that control whether specific functions are compiled.

function MyComponent() {
  "use memo"; // Opt this component into compilation
  return <div>{/* ... */}</div>;
}

概述

¥Overview

React Compiler 指令可以对编译器优化哪些函数进行细粒度的控制。它们是位于函数体开头或模块顶部的字符串字面量。

¥React Compiler directives provide fine-grained control over which functions are optimized by the compiler. They are string literals placed at the beginning of a function body or at the top of a module.

可用指令

¥Available directives

快速比较

¥Quick comparison

指令目的何时使用
"use memo"强制编译使用 annotation 模式或覆盖 infer 模式启发式算法时
"use no memo"阻止编译调试问题或使用不兼容的代码

用法

¥Usage

函数级指令

¥Function-level directives

将指令放置在函数开头以控制其编译：

¥Place directives at the beginning of a function to control its compilation:

// Opt into compilation
function OptimizedComponent() {
  "use memo";
  return <div>This will be optimized</div>;
}

// Opt out of compilation
function UnoptimizedComponent() {
  "use no memo";
  return <div>This won't be optimized</div>;
}

模块级指令

¥Module-level directives

将指令放置在文件顶部以影响该模块中的所有函数：

¥Place directives at the top of a file to affect all functions in that module:

// At the very top of the file
"use memo";

// All functions in this file will be compiled
function Component1() {
  return <div>Compiled</div>;
}

function Component2() {
  return <div>Also compiled</div>;
}

// Can be overridden at function level
function Component3() {
  "use no memo"; // This overrides the module directive
  return <div>Not compiled</div>;
}

编译模式交互

¥Compilation modes interaction

指令的行为会根据你的 compilationMode 而有所不同：

¥Directives behave differently depending on your compilationMode:

  • annotation 模式：仅编译带有 "use memo" 指令的函数

    ¥**annotation mode**: Only functions with "use memo" are compiled

  • infer 模式：编译器决定编译什么，指令覆盖决定

    ¥**infer mode**: Compiler decides what to compile, directives override decisions

  • all 模式：所有内容都已编译，"use no memo" 可以排除特定函数

    ¥**all mode**: Everything is compiled, "use no memo" can exclude specific functions

最佳实践

¥Best practices

谨慎使用指令

¥Use directives sparingly

指令是应急方案。建议在项目级别配置编译器：

¥Directives are escape hatches. Prefer configuring the compiler at the project level:

// ✅ Good - project-wide configuration
{
  plugins: [
    ['babel-plugin-react-compiler', {
      compilationMode: 'infer'
    }]
  ]
}

// ⚠️ Use directives only when needed
function SpecialCase() {
  "use no memo"; // Document why this is needed
  // ...
}

文档指令用法

¥Document directive usage

请务必解释使用指令的原因：

¥Always explain why a directive is used:

// ✅ Good - clear explanation
function DataGrid() {
  "use no memo"; // TODO: Remove after fixing issue with dynamic row heights (JIRA-123)
  // Complex grid implementation
}

// ❌ Bad - no explanation
function Mystery() {
  "use no memo";
  // ...
}

移除计划

¥Plan for removal

选择退出指令应该是临时的：

¥Opt-out directives should be temporary:

  1. 添加带有 TODO 注释的指令

    ¥Add the directive with a TODO comment

  2. 创建跟踪问题

    ¥Create a tracking issue

  3. 修复潜在问题

    ¥Fix the underlying problem

  4. 删除该指令

    ¥Remove the directive

function TemporaryWorkaround() {
  "use no memo"; // TODO: Remove after upgrading ThirdPartyLib to v2.0
  return <ThirdPartyComponent />;
}

常见模式

¥Common patterns

逐步采用

¥Gradual adoption

在大型代码库中采用 React 编译器时：

¥When adopting the React Compiler in a large codebase:

// Start with annotation mode
{
  compilationMode: 'annotation'
}

// Opt in stable components
function StableComponent() {
  "use memo";
  // Well-tested component
}

// Later, switch to infer mode and opt out problematic ones
function ProblematicComponent() {
  "use no memo"; // Fix issues before removing
  // ...
}

故障排除

¥Troubleshooting

有关指令的具体问题，请参阅以下位置的故障排除部分：

¥For specific issues with directives, see the troubleshooting sections in:

常见问题

¥Common issues

  1. 忽略指令：检查位置（必须放在最前面）和拼写

    ¥Directive ignored: Check placement (must be first) and spelling

  2. 仍然发生编译：检查 ignoreUseNoForget 设置

    ¥Compilation still happens: Check ignoreUseNoForget setting

  3. 模块指令不起作用：确保它位于所有导入之前

    ¥Module directive not working: Ensure it’s before all imports

另请参阅

¥See also

上一章target
下一章"use memo"