自动链接

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

通常，当你开发原生移动应用并想要安装第三方库时，系统会要求你将依赖添加到包管理器的清单文件中（Android 上的 build.gradle、iOS 上的 CocoaPods 的 Podfile、 iOS 上 SwiftPM 的 Package.swift）。在 Expo 和 React Native 中，你已经通过从 npm 注册表安装包来使用 package.json 文件执行此操作。由于大多数 React Native 库都附带了一些原生（特定于平台的）代码，因此安装库甚至需要配置最多三个不同的包管理器！

¥Usually, when you're developing a native mobile app and want to install a third-party library, you're asked to add the dependency to the manifest files of your package managers (build.gradle on Android, Podfile for CocoaPods on iOS, Package.swift for SwiftPM on iOS). In Expo and React Native, you already do that with your package.json file by installing the package from the npm registry. Since most of the React Native libraries come with some native (platform-specific) code, installing a library will require configuring even up to three different package managers!

Expo Autolinking 是一种自动执行此过程并将库安装过程减少到最少的机制 - 通常只需从 npm 安装软件包并重新运行 pod install。核心实现可以在 expo-modules-autolinking 包中找到，分为三个部分：

¥Expo Autolinking is a mechanism that automates this process and reduces the library installation process to the minimum — usually just installing the package from npm and re-running pod install. The core implementation can be found in the expo-modules-autolinking package and is divided into three parts:

1. 具有模块解析算法的通用 JavaScript CLI 工具

   ¥common JavaScript CLI tool with the module resolution algorithm

2. 与 Android 平台的 Gradle 构建系统集成的代码

   ¥code that integrates with the Gradle build system for Android platform

3. 与 iOS 平台的 CocoaPods 集成的 Ruby 脚本

   ¥Ruby script that integrates with CocoaPods for iOS platform

CLI 命令

¥CLI commands

{
  "expo-random": {
    "path": "/absolute/path/to/node_modules/expo-random",
    "version": "13.0.0",
    "config": {
      // Contents of `expo-module.config.json`
      "platforms": ["ios", "android"],
      "ios": { "modules": ["RandomModule"] },
      "android": { "modules": ["expo.modules.random.RandomModule"] }
    },
    "duplicates": [] // An array of other revisions (with lower precedence) of the same module
  }
  // more modules...
}

{
  "modules": [
    {
      "packageName": "expo-random",
      "packageVersion": "13.0.0",
      "pods": [
        {
          "podName": "ExpoRandom",
          "podspecDir": "/absolute/path/to/node_modules/expo-random/ios"
        }
      ],
      "swiftModuleNames": ["ExpoRandom"],
      "modules": ["RandomModule"],
      "appDelegateSubscribers": [],
      "reactDelegateHandlers": [],
      "debugOnly": false
    }
    // more modules...
  ]
}

配置

¥Configuration

可以使用一些配置选项来自定义模块解析的行为。这些选项可以在三个不同的位置定义，从最低优先级到最高优先级：

¥The behavior of the module resolution can be customized using some configuration options. These options can be defined in three different places, from the lowest to the highest precedence:

• 应用的 package.json 中的 expo.autolinking 配置对象

  ¥expo.autolinking config object in application's package.json

• 每个平台使用 expo.autolinking.ios 和 expo.autolinking.android 对象覆盖

  ¥per platform overrides with expo.autolinking.ios and expo.autolinking.android objects

• 提供给 CLI 命令的选项、Podfile 中的 use_expo_modules! 方法或 settings.gradle 中的 useExpoModules 函数

  ¥options provided to the CLI command, the use_expo_modules! method in the Podfile or useExpoModules function in the settings.gradle

{
  "expo": {
    "autolinking": {
      "searchPaths": ["../../packages"]
    }
  }
}

{
  "expo": {
    "autolinking": {
      "android": {
        "exclude": ["expo-random"]
      }
    }
  }
}

module.exports = {
  dependencies: {
    'library-name': {
      platforms: {
        android: null,
      },
    },
  },
};

use_expo_modules!({
  flags: {
    :inhibit_warnings => false
  }
})

{
  "expo": {
    "autolinking": {
      "ios": {
        "flags": {
          "inhibit_warnings": true
        }
      }
    }
  }
}

常见问题

¥Common questions

如何在我的应用中设置自动链接？

¥How to set up the autolinking in my app?

使用 npx create-expo-app 命令创建的所有项目都已配置为使用 Expo 自动链接。如果你的项目是使用不同的工具创建的，请参阅 安装 Expo 模块 以确保你的项目包含所有必要的更改。

¥All projects created with the npx create-expo-app command are already configured to use Expo Autolinking. If your project was created using different tools, please refer to Installing Expo modules to make sure your project includes all necessary changes.

我的模块中需要有什么才能使其可自动链接？

¥What do I need to have in my module to make it autolinkable?

模块解析算法仅搜索根目录中 package.json 文件旁边包含 Expo 模块配置 文件 (expo-module.config.json) 的包。还需要在 platforms 数组中包含支持的平台 - 如果运行自动链接算法的平台不存在于该数组中，则只会在搜索结果中跳过它。

¥The module resolution algorithm searches only for packages that contain the Expo module config file (expo-module.config.json) at the root directory, next to the package.json file. It's also necessary to include supported platforms in the platforms array — if the platform for which the autolinking algorithm is run is not present in this array, it's just skipped in the search results.

它与 React Native 自动链接有何不同？

¥How is it different from React Native autolinking?

• Expo Autolinking 内置了对 monorepos、Yarn 工作区和传递依赖的支持。

  ¥Expo Autolinking comes in with built-in support for monorepos, Yarn workspaces and transitive dependencies.

• 即使模块解析算法更复杂，也更可靠并与节点的模块解析相匹配，它的速度也明显更快。

  ¥It's also significantly faster, even though the module resolution algorithm is more complex to be more reliable and match the Node's module resolution.

• Expo 模块解析还能够检测重复项，这是 monorepos 中的常见问题。

  ¥Expo module resolution is also capable of detecting the duplicates which is a common issue in monorepos.

• 最后但并非最不重要的一点是，它与 Expo Modules API 提供的所有功能很好地集成。

  ¥Last but not least, it integrates well with all the features offered by Expo Modules APIs.