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 应用内创建本地模块，或创建带有示例应用的独立模块，用于开发和测试原生代码。

本地和独立模块

🌐 Local and standalone modules

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

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

🌐 A local module lives inside a single Expo project. Use a local module when you want to add custom native code to one app and do not need to publish or share it as a separate package. Local modules use the app's dependencies and tooling, and they are automatically discovered by Expo Autolinking from the project's native modules directory.

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

🌐 A standalone module is its own package. Use a standalone module when you want to reuse the module across multiple apps, keep it in a monorepo package, or publish it to npm. Standalone modules include package metadata, their own dependencies and scripts, and an example app for developing and testing the module.

创建本地模块

🌐 Create a local module

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

🌐 To create a local module inside an existing Expo project, navigate to the project directory and run the following command:

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

🌐 Running the above command will prompt you to enter the local module name, native module name, target platforms, and feature examples to include.

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

🌐 Local modules are created in the modules directory by default. If your project's package.json defines expo.autolinking.nativeModulesDir, the module is created in that directory instead.

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

🌐 A local module includes the module config, JavaScript or TypeScript source files, and native files for the selected platforms. For example, a module with Android and Apple support includes:

创建独立模块

🌐 Create a standalone module

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

🌐 To create a standalone Expo module, run the following command:

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

🌐 Running the above command will prompt you for the package name, native module name, target platforms, feature examples, package metadata, and package manager. It generates the module and an example app that you can use to build and test the module on Android and iOS.

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

🌐 The generated module includes package metadata, TypeScript configuration, native platform files, module source files, and an example app. For example, a module with Android and Apple support includes:

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

🌐 If the module is not created inside an existing Git repository, the command initializes a new Git repository and creates an initial commit.

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

🌐 When the example app is created, the command installs dependencies and runs Prebuild for the app. On macOS, it also installs CocoaPods for the generated iOS project.

开发一个独立模块

🌐 Develop a standalone module

创建独立模块后，导航到模块目录并打开生成的原生项目：

🌐 After creating a standalone module, navigate to the module directory and open the generated native projects:

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

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

🌐 Then start the development server from the example directory:

独立模块包括以下脚本：

🌐 Standalone modules include the following scripts:

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

🌐 When you change native code, rebuild the example app to see the changes. JavaScript and TypeScript changes are picked up by the development server.

选项

🌐 Options

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

🌐 Use the following options to customize the command's behavior.

[path]

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

🌐 Creates the module at the provided path. If omitted, the command uses the name from the prompt.

--local

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

🌐 Creates a local module inside the current Expo project. Local modules skip installing module dependencies and do not create an example app.

--platform

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

🌐 Selects the platforms the module should support. Available values are android, apple, and web.

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

🌐 For local modules, the interactive prompt preselects platforms from the app config's platforms property when it is available. For standalone modules, all platforms are preselected by default. In non-interactive mode, all platforms are used unless this option is provided.

例如，要创建一个安卓和苹果模块：

🌐 For example, to create an Android and Apple module:

--features

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

🌐 Selects which feature examples to include in the generated module. Feature examples are small, working snippets in the generated files that show how to define common Expo Modules API features. They are meant to give you a starting point for your own implementation, not to declare what your module is allowed to support.

可用功能示例如下：

🌐 Available feature examples are:

例如：

🌐 For example:

使用 all 来包含每个功能示例：

🌐 Use all to include every feature example:

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

🌐 If you do not select any feature examples, the command creates a minimal module.

--full-example

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

🌐 Includes all available feature examples. This is equivalent to passing --features all.

--package-manager

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

🌐 Selects the package manager used for standalone modules. Available values are npm, pnpm, yarn, and bun.

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

🌐 If omitted, the command detects the package manager from the current process or from the package managers available on your system. In interactive mode, the detected package manager is preselected.

--no-example

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

🌐 Skips creating the example app for a standalone module.

--barrel

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

🌐 Generates an index.ts barrel file for local modules. This option only applies with --local.

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

🌐 By default, local modules do not generate a barrel file, so imports point directly to files in the module's src directory.

--source

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

🌐 Uses a local template directory instead of downloading expo-module-template from npm. Pass the root directory of an expo-module-template package.

--with-readme

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

🌐 Includes a README.md file in a standalone module.

--with-changelog

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

🌐 Includes a CHANGELOG.md file in a standalone module.

--name

设置本地模块名称，例如 MyModule。如果名称与 Apple 框架冲突，该命令将重命名以避免本地构建错误。

🌐 Sets the native module name, for example MyModule. If the name conflicts with an Apple framework, the command renames it to avoid native build errors.

--description

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

🌐 Sets the module description used in package metadata.

--package

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

🌐 Sets the Android package name, for example expo.modules.mymodule.

--author-name

设置包作者名称。

🌐 Sets the package author name.

--author-email

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

🌐 Sets the package author email address.

--author-url

设置软件包作者的个人资料网址。

🌐 Sets the package author profile URL.

--repo

设置软件包仓库的 URL。

🌐 Sets the package repository URL.

--license

设置包的许可证。默认值是 MIT。

🌐 Sets the package license. The default is MIT.

--module-version

设置初始软件包版本。默认值是 0.1.0。

🌐 Sets the initial package version. The default is 0.1.0.

--version

打印版本号并退出。

🌐 Prints the version number and exits.

--help

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

🌐 Prints the list of available options and exits.

非交互模式

🌐 Non-interactive mode

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

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

🌐 In non-interactive mode, values that are not passed explicitly are filled with defaults and printed as warnings. For example, the command can derive the package name from the target path and use defaults for the native module name, Android package name, description, license, and initial version.

在需要稳定生成值时明确传递选项：

🌐 Pass options explicitly when you need stable generated values:

对于本地模块，非交互模式也默认适用于所有平台，除非提供了 --platform。

🌐 For local modules, non-interactive mode also defaults to all platforms unless --platform is provided.

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

🌐 The add-platform-support command requires --platform in non-interactive mode:

添加平台支持

🌐 Add platform support

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

🌐 The add-platform-support command adds new platform files to an existing Expo module and updates expo-module.config.json.

注意: 此命令会扫描现有的原生模块定义，并尝试检测如 Function、AsyncFunction、View 和 SharedObject 的功能示例。功能检测尽力而为。对于遵循常规 Expo 模块 API 模式的模块，它运行良好，但对于不寻常的模块、具有生成代码的模块或定义分布在多个文件的大型模块，它可能无法正确检测功能。使用 --features 来覆盖检测到的功能示例。

对于本地模块，现有的实现需要使用 Expo 模块 API DSL，以便命令可以找到模块定义文件。不支持较旧的模块格式。

🌐 For native modules, the existing implementation needs to use the Expo Modules API DSL so the command can find the module definition file. Older module formats are not supported.

从模块根目录运行命令：

🌐 Run the command from the module root:

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

🌐 The command will prompt you to choose from the platforms that are not already supported by the module.

你也可以传递模块的路径：

🌐 You can also pass the path to the module:

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

🌐 The command only adds platforms that are not already listed in expo-module.config.json. It does not overwrite existing native platform directories, such as android or ios.

add-platform-support --platform

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

🌐 Selects the platforms to add. Available values are apple, android, and web.

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

🌐 In non-interactive mode, this option is required. In interactive mode, the command prompts you to choose from the platforms that are not already supported by the module.

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

🌐 For example, to add Android support without a prompt:

add-platform-support --features

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

🌐 Overrides the feature examples used when generating files for the new platform.

如果生成的文件与你的模块不匹配，请明确传递 --features：

🌐 If the generated files do not match your module, pass --features explicitly:

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

🌐 If no features are detected or provided, the command generates a minimal scaffold for the new platform.

add-platform-support --source

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

🌐 Uses a local template directory instead of downloading expo-module-template from npm.

模板版本

🌐 Template versions

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

🌐 By default, create-expo-module downloads expo-module-template from npm.

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

🌐 Standalone modules use the latest template. Local modules try to use the template version that matches the Expo SDK version installed in the current project, and fall back to the latest template when the SDK version cannot be detected.

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

🌐 To test beta releases, set EXPO_BETA=1 before running the command:

环境变量

🌐 Environment variables

EXPO_BETA

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

🌐 Uses the next version of the module and example app templates.

EXPO_DEBUG

为该命令启用调试日志。

🌐 Enables debug logs for the command.

EXPO_NO_TELEMETRY

禁用遥测。

🌐 Disables telemetry.

EXPO_NONINTERACTIVE

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

🌐 Runs the command in non-interactive mode and skips prompts.

了解更多

🌐 Learn more