create-expo-module

用于创建和更新 Expo 模块的命令行工具。

For the complete documentation index, see llms.txt. Use this file to discover all available pages.

create-expo-module 是一个命令行工具，用于创建新的 Expo 模块或为现有模块添加平台支持。它可以在 Expo 应用内创建本地模块，也可以创建一个带示例应用的独立模块，用于开发和测试原生代码。

本地模块与独立模块

create-expo-module 可以创建两种类型的模块：本地模块和独立模块。

本地模块 存在于单个 Expo 项目中。当你想为某个应用添加自定义原生代码，并且不需要将其发布或作为单独的包共享时，请使用本地模块。本地模块使用应用的依赖项和工具链，并且会被 Expo Autolinking 自动从项目的原生模块目录中发现。

独立模块 是一个独立的包。当你想在多个应用之间复用该模块、将其保留在 monorepo 包中，或将其发布到 npm 时，请使用独立模块。独立模块包含包元数据、自己的依赖项和脚本，以及一个用于开发和测试该模块的示例应用。

创建本地模块

要在现有的 Expo 项目中创建本地模块，请进入项目目录并运行以下命令：

运行上述命令后，系统会提示你输入本地模块名称、原生模块名称、目标平台以及要包含的功能示例。

默认情况下，本地模块会创建在 modules 目录中。如果你的项目 package.json 定义了 expo.autolinking.nativeModulesDir，则模块会创建在该目录中。

本地模块包含模块配置、JavaScript 或 TypeScript 源文件，以及所选平台的原生文件。例如，一个支持 Android 和 Apple 的模块包括：

创建独立模块

要创建一个独立的 Expo 模块，请运行以下命令：

运行上述命令后，系统会提示你输入包名、原生模块名称、目标平台、功能示例、包元数据以及包管理器。它会生成模块和一个 example 应用，你可以用它在 Android 和 iOS 上构建并测试模块。

生成的模块包含包元数据、TypeScript 配置、原生平台文件、模块源文件以及一个 example 应用。例如，一个支持 Android 和 Apple 的模块包括：

如果模块不是在现有的 Git 仓库中创建的，该命令会初始化一个新的 Git 仓库并创建初始提交。

在创建 example 应用时，该命令会安装依赖并为该应用运行 Prebuild。在 macOS 上，它还会为生成的 iOS 项目安装 CocoaPods。

开发独立模块

创建独立模块后，进入模块目录并打开生成的原生项目：

注意： open:ios 脚本需要 macOS 和 Xcode。在 Windows 上，请在 Android Studio 中打开生成的 android 目录。

然后从 example 目录启动开发服务器：

独立模块包含以下脚本：

当你修改原生代码时，请重新构建示例应用以查看更改。JavaScript 和 TypeScript 的更改会被开发服务器自动捕获。

选项

使用以下选项来自定义命令行为。

[path]

在提供的路径创建模块。如果省略，命令会使用提示中的名称。

--local

在当前 Expo 项目中创建本地模块。本地模块会跳过安装模块依赖，并且不会创建示例应用。

--platform

选择模块应支持的平台。可用值为 android、apple 和 web。

对于本地模块，当应用配置的 platforms 属性可用时，交互式提示会预先选择其中的平台。对于独立模块，默认会预先选择所有平台。在非交互模式下，除非提供此选项，否则会使用所有平台。

例如，要创建一个支持 Android 和 Apple 的模块：

--features

选择要在生成的模块中包含哪些功能示例。功能示例是生成文件中的简短可运行代码片段，用于展示如何定义常见的 Expo Modules API 功能。它们旨在为你自己的实现提供起点，而不是声明你的模块允许支持什么。

可用的功能示例如下：

例如：

使用 all 可包含所有功能示例：

如果你没有选择任何功能示例，命令会创建一个最小模块。

--full-example

包含所有可用的功能示例。这等同于传递 --features all。

--package-manager

选择用于独立模块的包管理器。可用值为 npm、pnpm、yarn 和 bun。

如果省略，命令会从当前进程或系统中可用的包管理器中检测包管理器。在交互模式下，检测到的包管理器会被预先选中。

--no-example

跳过为独立模块创建 example 应用。

--barrel

为本地模块生成一个 index.ts 汇总文件。此选项仅适用于 --local。

默认情况下，本地模块不会生成汇总文件，因此导入会直接指向模块 src 目录中的文件。

--source

使用本地模板目录，而不是从 npm 下载 expo-module-template。请传入 expo-module-template 包的根目录。

--with-readme

在独立模块中包含一个 README.md 文件。

--with-changelog

在独立模块中包含一个 CHANGELOG.md 文件。

--name

设置原生模块名称，例如 MyModule。如果该名称与 Apple framework 冲突，命令会对其重命名以避免原生构建错误。

--description

设置包元数据中使用的模块描述。

--package

设置 Android 包名，例如 expo.modules.mymodule。

--author-name

设置包作者名称。

--author-email

设置包作者电子邮件地址。

--author-url

设置包作者主页 URL。

--repo

设置包仓库 URL。

--license

设置包许可证。默认值为 MIT。

--module-version

设置初始包版本。默认值为 0.1.0。

--version

打印版本号并退出。

--help

打印可用选项列表并退出。

非交互模式

create-expo-module 在非交互式环境中运行时会跳过提示。这包括 CI、EXPO_NONINTERACTIVE，以及 stdin 不是 TTY 的终端。

在非交互模式下，未显式传入的值会使用默认值填充，并以警告形式打印。例如，命令可以从目标路径推导包名，并对原生模块名称、Android 包名、描述、许可证和初始版本使用默认值。

当你需要稳定的生成值时，请显式传入选项：

对于本地模块，若未提供 --platform，非交互模式也会默认使用所有平台。

add-platform-support 命令在非交互模式下需要 --platform：

添加平台支持

add-platform-support 命令会向现有 Expo 模块添加新的平台文件，并更新 expo-module.config.json。

注意： 该命令会扫描现有的原生模块定义，并尝试检测诸如 Function、AsyncFunction、View 和 SharedObject 等功能示例。功能检测仅尽力而为。它对遵循常规 Expo Modules API 模式的模块效果很好，但对于不常见的模块、包含生成代码的模块，或定义分散在多个文件中的大型模块，可能无法正确检测功能。使用 --features 可覆盖检测到的功能示例。

对于原生模块，现有实现需要使用 Expo Modules API DSL，这样命令才能找到模块定义文件。不支持旧版模块格式。

从模块根目录运行命令：

命令会提示你从该模块尚未支持的平台中进行选择。

你也可以传入模块路径：

该命令只会添加 expo-module.config.json 中尚未列出的平台。它不会覆盖现有的原生平台目录，例如 android 或 ios。

add-platform-support --platform

选择要添加的平台。可用值为 apple、android 和 web。

在非交互模式下，此选项是必需的。在交互模式下，命令会提示你从该模块尚未支持的平台中进行选择。

例如，要在不提示的情况下添加 Android 支持：

add-platform-support --features

覆盖为新平台生成文件时使用的功能示例。

如果生成的文件不符合你的模块，请显式传入 --features：

如果未检测到或未提供任何功能，命令会为新平台生成最小骨架。

add-platform-support --source

使用本地模板目录，而不是从 npm 下载 expo-module-template。

模板版本

默认情况下，create-expo-module 会从 npm 下载 expo-module-template。

独立模块使用最新模板。本地模块会尝试使用与当前项目中安装的 Expo SDK 版本匹配的模板版本；如果无法检测到 SDK 版本，则回退到最新模板。

要测试 beta 版本，请在运行命令前设置 EXPO_BETA=1：

环境变量

EXPO_BETA

使用模块和示例应用模板的下一个版本。

EXPO_DEBUG

为该命令启用调试日志。

EXPO_NO_TELEMETRY

禁用遥测。

EXPO_NONINTERACTIVE

以非交互模式运行命令并跳过提示。

了解更多