预编译的 Expo 模块

将 expo-build-properties 配置插件的 ios.usePrecompiledModules 属性设置为 false，以从源代码构建每个 Expo 模块。这适用于本地构建和 EAS 构建，并将在下次运行 npx expo prebuild 时生效：

🌐 Set the ios.usePrecompiledModules property of the expo-build-properties config plugin to false to build every Expo Module from source. This applies to both local builds and EAS Build, and takes effect the next time you run npx expo prebuild:

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "usePrecompiledModules": false
          }
        }
      ]
    ]
  }
}

或者，你可以直接通过 EXPO_USE_PRECOMPILED_MODULES 环境变量来控制，它会在 pod install 期间读取。对于本地构建，在运行 pod install（或 npx expo run:ios）之前在你的 shell 中导出它：

🌐 Alternatively, you can control this directly with the EXPO_USE_PRECOMPILED_MODULES environment variable, which is read during pod install. For local builds, export it in your shell before running pod install (or npx expo run:ios):

对于 EAS Build，请创建一个 EAS 环境变量：

🌐 For EAS Build, create an EAS environment variable:

CLI 会提示你选择该变量适用于哪些环境（development、preview、production）。

🌐 The CLI will prompt you to select which environment(s) (development, preview, production) the variable applies to.

在 package.json 中使用 buildFromSource 配置 Expo 自动链接。使用 ".*" 可以选择退出所有预编译模块，或列出特定的包名称。相同的设置也适用于 android 和 ios：

🌐 Configure Expo Autolinking with buildFromSource in package.json. Use ".*" to opt out of every precompiled module, or list specific package names. The same setting is available for both android and ios:

{
  "name": "your-app-name",
  "expo": {
    "autolinking": {
      "android": {
        "buildFromSource": [".*"]
      },
      "ios": {
        "buildFromSource": [".*"]
      }
    }
  }
}

通常只有在你自己修改模块源代码时才需要这样做。

🌐 This is typically only needed when you're modifying module source code yourself.

iOS

在 EAS Build 上，第三方库如 react-native-reanimated 和 react-native-worklets 会自动作为预编译的 XCFramework 下载。本地的 pod install 默认不会获取它们。这些包会在本地从源码构建，并自动应用任何 staticFeatureFlags 的覆盖，因此标志和版本不匹配主要会在 EAS Build 上显现。避免为本地构建启用第三方预编译下载，并将此路径限制在 EAS。

🌐 On EAS Build, third-party libraries like react-native-reanimated and react-native-worklets are automatically downloaded as precompiled XCFrameworks. Local pod install does not fetch them by default. Those packages build from source locally and pick up any staticFeatureFlags overrides automatically, so flag and version mismatches surface primarily on EAS Build. Avoid enabling third-party precompiled downloads for local builds and keep this path scoped to EAS.

react-native-reanimated 和 react-native-worklets

🌐 react-native-reanimated and react-native-worklets

这两个包紧密耦合。react-native-reanimated 在本地层面链接 react-native-worklets。

🌐 These two packages are tightly coupled. react-native-reanimated links react-native-worklets at the native level.

同时选择退出。 如果你需要为任一软件包构建源代码（例如应用补丁或修改原生代码），请在 buildFromSource 中列出两者。仅构建其中一个源代码会产生混合的预编译/源代码链接，在运行时无法解析匹配的框架：

{
  "expo": {
    "autolinking": {
      "ios": {
        "buildFromSource": ["react-native-reanimated", "react-native-worklets"]
      }
    }
  }
}

自定义功能标志需要源代码构建。 功能标志的值在构建时会写入预编译二进制文件，因此 package.json 中的任何 worklets.staticFeatureFlags 或 reanimated.staticFeatureFlags 覆盖将被忽略。要应用它们，请使用 EXPO_USE_PRECOMPILED_MODULES=0 禁用预编译模块。

何时查看此处。 在 EAS 构建中出现像 Unable to recognize flag: <NAME> 这样的运行时错误（但本地没有）意味着预编译工件的标志列表与你固定的包版本不匹配。使用上面的 buildFromSource 并且 在 GitHub 上提交问题。