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

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

概述

🌐 Overview

React 编译器指令提供对编译器优化哪些函数的细粒度控制。它们是字符串字面量，放在函数体的开头或模块的顶部。

🌐 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" 的函数会被编译
  • infer 模式：编译器决定编译内容，指令可以覆盖这些决定
  • all 模式：一切都会被编译，"use no memo" 可以排除特定函数

最佳实践

🌐 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 注释的指令
  2. 创建跟踪问题
  3. 修复潜在问题
  4. 删除该指令
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. 指令被忽略：检查位置（必须在第一位）和拼写
  2. 编译仍然会发生：检查 ignoreUseNoForget 设置
  3. 模块指令不起作用：确保它位于所有导入之前

另请参阅

🌐 See also

上一章target
下一章"use memo"