Ignite 模板中的 plugins 目录用 Expo Config Plugins 定制原生配置的完整指南【免费下载链接】igniteInfinite Reds battle-tested React Native project boilerplate, along with a CLI, component/model generators, and more! 9 years of continuous development and counting.项目地址: https://gitcode.com/GitHub_Trending/ig/ignite本文以 Ignite 锅炉板boilerplate中 plugins 目录文档 为核心骨架系统讲解 Expo Config Plugins 的作用机制、在 Ignite 应用中的目录约定以及如何通过app.config.ts将自定义插件接入构建流程。读完本文你将掌握「零原生代码改动」地注入原生配置的方法能够为应用添加或修改 Expo 插件并理解 Ignite 锅炉板自带的app.json/app.config.ts双层配置是如何协作的。为什么要有一个 plugins 目录在 Ignite 生成的 Expo 应用中原生工程iOS 的 Xcode 工程、Android 的 Gradle 工程默认不是由你手工维护的而是由prebuild预构建过程在构建时生成或同步的。这一工作流在 Expo 生态中被称为 Continuous Native GenerationCNG你维护的是一份配置即源码原生代码则由 Expo 根据配置自动生成。CNG 工作流带来的直接收益是不需要直接操作 Gradle 与 CocoaPods升级依赖时无需反复迁移手工的原生代码修改大量流行库都提供现成的 Config Plugins且自定义 Config Plugin 的编写是官方支持的。在这套体系下如果你需要调整原生配置——比如修改 iOS 权限声明、Android 清单、启动屏参数、字体加载等——正确姿势不是去ios/、android/目录里手工改文件那会被下一次 prebuild 覆盖而是编写一个Expo Config Plugin。Ignite 锅炉板因此专门在项目根目录约定了一个plugins目录按照 Boilerplate.md 对目录结构的说明它用于存放在 prebuild 生成原生代码过程中需要应用的、任何自定义的 Expo Config Plugins。配置解析链路app.json → app.config.ts → plugins 数组要理解插件如何生效先要看清 Ignite 锅炉板的两层配置文件详见 app.json/app.config.ts 说明app.json静态配置。包含应用名、slug、图标、iOS/Android 基础设置等也包含默认的plugins数组app.config.ts动态配置。它接收从app.json解析出来的ExpoConfig经过处理后输出 Expo 的最终配置。app.config.ts的核心实现如下import { ExpoConfig, ConfigContext } from expo/config // 使用 tsx/cjs让 Config Plugins 可以直接用 TypeScript 编写而无需预编译 import tsx/cjs module.exports ({ config }: ConfigContext): PartialExpoConfig { const existingPlugins config.plugins ?? [] return { ...config, ios: { ...config.ios, privacyManifests: { NSPrivacyAccessedAPITypes: [ { NSPrivacyAccessedAPIType: NSPrivacyAccessedAPICategoryUserDefaults, NSPrivacyAccessedAPITypeReasons: [CA92.1], }, ], }, }, plugins: [...existingPlugins], } }这段代码透露了几个关键设计config.plugins ?? []动态配置先读取静态配置app.json里已有的插件数组保证自定义逻辑永远建立在既有插件之上而不是覆盖它们plugins: [...existingPlugins]最终返回的配置把原有插件原样透传你添加的新插件也应追加到这个数组中import tsx/cjs这是 Ignite 让 Config Plugins 直接用 TypeScript 编写、无需手工编译成 JS 的关键一行iOS privacyManifests锅炉板默认注入了一份 Apple 隐私清单起步配置UserDefaults访问原因CA92.1这是为了满足苹果隐私清单要求而内置的示例可根据应用实际使用的 API 继续扩充。如何添加自定义插件两步接入根据 Plugins.md 的说明在 Ignite 应用中接入自定义 Config Plugin 只需两步第 1 步创建插件在项目根目录的plugins目录下新建一个 TypeScript 文件导出一个修改ExpoConfig的函数。这个函数会被 Expo 在 prebuild 时调用返回修改后的配置对象或通过 mods 修改原生工程文件。第 2 步接入动态配置在 app.config.ts 中导入你的插件并追加到plugins数组// In app.config.ts plugins: [...existingPlugins, require(./plugins/yourCustomPlugin).yourCustomPlugin]这里有两个值得注意的细节使用require而不是import因为app.config.ts本身以 CommonJS 形式导出同时配合tsx/cjs也能解析 TypeScript 编写的插件文件插件文件被组织在plugins目录下路径以项目根目录为基准例如./plugins/yourCustomPlugin。一个完整的自定义插件示例把两步串起来一个最小可用的自定义插件长这样。在plugins/下创建withAppName.tsimport { ConfigPlugin, withInfoPlist } from expo/config-plugins // 一个典型的 Config Plugin接收 config返回修改后的 config const withCustomAppName: ConfigPlugin{ appName?: string } (config, props) { // 示例通过 mods 修改 iOS 的 Info.plist return withInfoPlist(config, (config) { config.modResults.CFBundleDisplayName props?.appName ?? My Ignite App return config }) } export { withCustomAppName }然后在app.config.ts的返回对象中接入module.exports ({ config }: ConfigContext): PartialExpoConfig { const existingPlugins config.plugins ?? [] return { ...config, plugins: [ ...existingPlugins, [require(./plugins/withAppName).withCustomAppName, { appName: 示例应用 }], ], } }注意插件在数组中可以有两种写法字符串形式expo-font不带参数元组形式[expo-splash-screen, { image: ... }]第二项是传给插件的配置对象。锅炉板自带的插件实例从 app.json 看配置参数打开 Ignite 锅炉板的 app.json可以看到默认plugins数组已经预置了 5 个插件它们是理解插件参数写法的现成范例插件写法关键参数expo-localization字符串无参数启用本地化能力expo-font字符串无参数支持加载自定义字体expo-splash-screen元组image启动图路径、imageWidth300、resizeModecontain、backgroundColor#191015react-native-edge-to-edge元组android.parentThemeLight、android.enforceNavigationBarContrastfalseexpo-build-properties字符串无参数暴露 EAS 构建时的原生构建属性配置以expo-splash-screen为例它的参数写法展示了元组形式插件的通用结构第一个元素是模块名第二个元素是传给插件的 props 对象。这种结构同样适用于你自己编写的带参插件。另外从 Ignite CLI 的 new.ts 源码可以看出生成项目时 CLI 会直接向app.json的plugins数组动态push插件例如实验性的expo-router这印证了plugins数组是 Expo 配置体系中一个可编程追加的入口。关键要点与 mods 的注意事项综合 Plugins.md 与锅炉板源码可以提炼出以下关键结论Config Plugins 的本质它们扩展应用的配置将原生模块的集成自动化——你写的是声明式的配置而不是维护一堆原生样板代码约定目录自定义插件统一创建在plugins目录并在app.config.ts中追加到plugins数组两个环节缺一不可复杂场景使用 mods对于超出配置字段范围的复杂原生定制如改 Gradle 脚本、改 AndroidManifest 的具体节点Expo 提供了mods修改器机制。但mods 必须谨慎使用——它们直接操作原生工程生成结果理解不深时容易造成难以排查的构建问题CI/构建验证插件是在 prebuild 阶段被调用的接入新插件后应重新生成并验证原生工程确认产物符合预期后再提交配置。进一步阅读plugins 目录官方说明app.json / app.config.ts 配置详解Ignite 锅炉板目录结构总览Expo CNGContinuous Native Generation工作流Expo 与 Ignite 的协作关系与 Config Plugin 定位动态配置实现boilerplate/app.config.ts静态配置与内置插件boilerplate/app.json【免费下载链接】igniteInfinite Reds battle-tested React Native project boilerplate, along with a CLI, component/model generators, and more! 9 years of continuous development and counting.项目地址: https://gitcode.com/GitHub_Trending/ig/ignite创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考