自动链接

编辑页面

了解如何使用 Expo 自动链接在你的 Expo 项目中自动链接原生依赖。

依赖解析与冲突

Autolinking 和 Node 解析的目标不同，Node 和 Metro 中的模块解析算法有时会发生冲突。如果你的应用包含被 autolinking 识别到的某个原生模块的重复安装，你的 JavaScript bundle 可能会同时包含该原生模块的两个版本，而 autolinking 和你的原生应用中只会包含一个版本。这可能会导致运行时崩溃，并带来兼容性风险。

这在隔离依赖或 monorepo 中尤其常见，你应该检查并去重依赖中的原生模块。

查找重复包

expo-doctor 会列出项目中的每个重复原生模块，以及每个安装项的路径：

Terminal

- npx expo-doctor

- yarn dlx expo-doctor

- pnpm dlx expo-doctor

- bunx expo-doctor

verify 命令会报告相同的重复项，但不会运行其他项目检查。去重依赖是完整的解决方案。有关每个包管理器的操作步骤，请参见解决依赖问题。

处理重复项

从 SDK 54 开始，你可以在应用配置中将 experiments.autolinkingModuleResolution 设置为 true，以自动将 autolinking 应用于 Expo CLI 和 Metro bundler。这将强制 Metro 解析到的依赖与 autolinking 解析到的原生模块保持一致。

app.json

{
  "expo": {
    "experiments": {
      "autolinkingModuleResolution": true
    }
  }
}

从 SDK 55 开始，针对 monorepo 中的应用，experiments.autolinkingModuleResolution 标志默认启用。

重复安装仍会保留在你的 node_modules 目录中，因此此标志是一种权宜之计，而不是去重依赖的替代方案。对于无法移除的重复项，可以使用此选项。

检查不是原生模块的包

重复项检查和 experiments.autolinkingModuleResolution 会作用于 autolinking 解析到的原生模块，以及内置的不得重复的包列表。不是原生模块的包在重复时也可能出现问题。一个常见示例是会创建 React context 或在模块级变量中保存状态的库。

将这些包添加到 include 选项中，即可用相同方式处理它们：

package.json

{
  "expo": {
    "autolinking": {
      "include": ["third-party-library"]
    }
  }
}

现在，npx expo-doctor 和 verify 命令会报告 third-party-library 的重复项。在打包时，experiments.autolinkingModuleResolution 会将该包解析为单个副本。不会有任何内容添加到原生构建中，因此列出不包含原生代码的包是安全的。

常见问题

如何在我的应用中设置 autolinking？

所有通过 npx create-expo-app 命令创建的项目都已经配置为使用 Expo Autolinking。如果你的项目是使用其他工具创建的，请查看安装 Expo 模块，以确保你的项目包含所有必要的更改。

我的模块中需要具备什么才能被 autolink？

模块解析算法只会搜索在根目录中、位于 package.json 文件旁边包含 Expo 模块配置文件（expo-module.config.json）的包。还需要在 platforms 数组中包含受支持的平台——如果运行 autolinking 算法的平台不在该数组中，它就会在搜索结果中被跳过。

它与 React Native 社区 CLI 的 autolinking 有什么不同？

Expo Autolinking 内置支持 monorepo、包管理器工作区、传递依赖，以及隔离依赖安装。
它也显著更快，尽管模块解析算法更复杂，但这样做是为了更可靠并匹配 Node.js 的模块解析。
Expo 模块解析也能够检测重复依赖，这是 monorepo 中的常见问题。
最后但同样重要的是，它与 Expo Modules APIs 提供的功能配合良好，并支持 React Native 模块。

对 React Native 模块停用 Expo Autolinking

从 SDK 52 开始，Expo Autolinking 默认会替代 React Native 社区 CLI 的 autolinking。如果你希望改用 React Native 社区 CLI 的 autolinking，请设置环境变量 EXPO_USE_COMMUNITY_AUTOLINKING=1，并将 @react-native-community/cli 作为 dev dependency 添加到你的项目中。

设置此环境变量后，Expo Autolinking 将不会用于解析 React Native 模块，但仍会继续对 Expo 模块进行 autolink。