Expo expo/config-plugins 变更记录解析6.0 到 57.0 的完整版本演进与升级要点【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expo本篇以 packages/expo/config-plugins/CHANGELOG.md 为主体完整梳理 Expo 原生配置插件包的每一次版本发布含 57.0.6 之前的全部历史记录与 Unpublished 开发中变更并结合仓库源码如 DevServer.ts、Package.ts逐项印证新增能力、破坏性变更与修复细节帮助你在升级expo/config-plugins时准确预判影响面、验证 prebuild 产物并排查插件解析问题。一、包定位与变更记录的阅读方式expo/config-plugins的定位在 README 中一句话说明它是从统一 JavaScript 接口生成原生应用代码的工具。app.json中的静态配置能覆盖大部分需求但复杂行为改 Gradle、改 Info.plist、改.pbxproj、改 entitlements必须直接操作原生工程文件——config plugins 和 modsmodifiers就是为此而生的。该包的 CHANGELOG 采用固定的语义化分区按版本倒序排列 Breaking changes破坏性变更升级前必读 New features新增能力 Bug fixes缺陷修复 Others行为调整、依赖更新、内部重构部分条目前缀[iOS]/[Android]/[Internal]标明平台或范围 3rd party library updates第三方依赖升级每个版本条目还会以_This version does not introduce any user-facing changes._显式标注无用户可见变更这类版本通常只是依赖或内部修复。调试插件解析时README 还定义了三个环境变量排查 CHANGELOG 中反复出现的plugin resolution类问题时可直接使用EXPO_DEBUG打印静态插件解析的调试信息EXPO_CONFIG_PLUGIN_VERBOSE_ERRORS在开启EXPO_DEBUG的前提下展示插件解析的全部错误信息EXPO_USE_UNVERSIONED_PLUGINS强制使用非版本化的回退插件而非已安装包内的本地版本副本仅限测试 CLI 使用。二、完整版本发布列表下表汇总 CHANGELOG 中记录的全部版本6.0.0 至 57.0.6 及 Unpublished标注每个版本是否有用户可见变更便于按时间线定位版本日期用户可见变更Unpublished未发布有iOS RCTMetroPort 插件、Gradle 赋值语法修复、iOS 27 全屏文档57.0.62026-07-22无57.0.52026-07-15无57.0.42026-07-15无57.0.32026-07-07有版本覆盖修复57.0.12026-06-27无57.0.02026-06-25无56.0.92026-06-15无56.0.82026-05-23无56.0.72026-05-20有插件文件扩展名支持56.0.62026-05-19无56.0.52026-05-13有intent filter 类型补全56.0.42026-05-13无56.0.32026-05-08无56.0.22026-05-06无56.0.12026-05-06无56.0.02026-05-05有SystemBars 破坏性变更等55.0.82026-04-07无55.0.72026-03-18有codeSignIdentity 参数55.0.62026-02-25有androidStatusBar 弃用55.0.52026-02-16无55.0.42026-02-03无55.0.32026-01-26有移除 slash 依赖55.0.22026-01-22无55.0.12026-01-22有模板存储权限 maxSdkVersion55.0.02026-01-21有iOS locales 等54.0.32025-12-04有glob 升级54.0.22025-10-01有Android 资源名校验54.0.12025-09-11无54.0.02025-09-10无11.0.7 ~ 11.0.12025-08-15 ~ 2025-09-02无共 7 个版本11.0.02025-08-13有活动别名、预测返回手势等10.1.22025-07-08有strings.xml 单引号修复10.1.12025-07-03无10.1.02025-07-01有应用名翻译插件10.0.32025-06-18有getenv 2.0.0 等10.0.22025-05-01有scheme 追加修复10.0.12025-04-30无10.0.02025-04-30有scheme 破坏性变更9.1.7 / 9.1.62025-04-23 ~ 25无9.1.52025-04-21有codeMod 辅助函数9.1.4 ~ 9.1.22025-04-08 ~ 149.1.1 有变更9.1.4/9.1.3/9.1.2 无9.1.02025-04-04有updates.useNativeDebug 等9.0.172025-03-11有version 平台覆盖9.0.162025-02-21无9.0.152025-02-06有disableAntiBrickingMeasures9.0.14 / 9.0.132025-01-08 ~ 10无9.0.122024-12-05有Windows 解析 scheme9.0.102024-11-242024-11-24有foregroundServiceType9.0.102024-11-202024-11-20有Windows 嵌套模块解析9.0.92024-11-12有移除 DevSettingsActivity9.0.82024-11-11无9.0.72024-11-07有循环引用、manifest 同步9.0.62024-11-05有Windows glob 路径9.0.52024-11-04无9.0.42024-10-29有移除 main 入口弃用警告9.0.32024-10-28有恢复 main 字段解析9.0.22024-10-24无9.0.12024-10-22有check-package 测试修复9.0.02024-10-22有withDevelopmentTeam 等8.0.92024-09-24有updates.useEmbeddedUpdate8.0.82024-07-11有extraMavenRepos 合并8.0.72024-07-03无8.0.62024-06-27有状态栏 translucent 修复8.0.52024-06-05有manifest queries 类型改进8.0.42024-05-01有Kotlin 关键字包名8.0.32024-04-25有privacy info 绝对路径修复8.0.22024-04-24有withPodfile8.0.12024-04-22有移除 fingerprint 警告8.0.02024-04-18有fingerprint 策略更名8.0.0-beta.02024-04-17有PrivacyInfo 插件等7.8.42024-01-18有finalized mod7.8.32024-01-05无7.8.22023-12-19有slugify 依赖7.8.12023-12-15有mergeContents 修复等7.8.02023-12-12有RN 0.73 支持7.7.02023-11-14有包名改写规则收紧7.6.02023-10-17有ManifestQuery 类型7.5.02023-09-15有getRuntimeVersion 改为异步破坏性7.4.02023-09-04有移除 classic updates破坏性7.3.12023-08-02有测试 fixtures 更新7.3.02023-07-28无7.2.42023-06-30有entitlements 忽略已有文件7.2.32023-06-29无7.2.22023-06-27有semver 升级7.2.12023-06-24有移除 withPackageManifest7.2.02023-06-21有xml2js 升级7.1.02023-06-13有RN 0.72 支持等7.0.02023-05-08有useClassicUpdates破坏性6.0.02023-02-03有Google/Facebook 配置破坏性变更以下章节按Unpublished 最新变更 → 破坏性变更 → 新功能 → 修复 → 依赖与内部重构 → React Native 版本对应关系展开完整继承 CHANGELOG 中每一条用户可见变更的原始描述。三、Unpublished当前开发分支的三项变更含源码印证CHANGELOG 顶部Unpublished段落记录了尚未发布的变更共三项恰好对应仓库中可以直接验证的源码。3.1 [iOS] 新增IOSConfig.DevServer.withMetroPort写入RCTMetroPortInfo.plist 键对应 packages/expo/config-plugins/src/ios/DevServer.ts。源码中的注释给出了完整的设计动机Expo 原生运行时ExpoReactNativeFactory在启动时读取 Info.plist 中的RCTMetroPort键来解析 Metro 开发服务器端口该键被设置为构建变量$(RCT_METRO_PORT)使expo run:ios --port n能一路传递到应用内部预编译的 React Native 会把编译期RCT_METRO_PORT固定为8081缺少此键时裸 dev 构建未装expo-dev-client总会回落到:8081导致多个项目同时运行时撞在同一台开发服务器上源码注释还明确这是 Android 侧react_native_dev_server_port资源在 iOS 上的对等实现。实现上通过createInfoPlistPlugin(setMetroPort, withMetroPort)封装DevServer.ts#L15-L24setMetroPort直接在 Info.plist 上追加[METRO_PORT_INFO_PLIST_KEY]: $(RCT_METRO_PORT)。3.2 修复getApplicationIdAsync与setPackageInBuildGradle不识别 Gradle 赋值语法修复针对applicationId ...等号赋值这种写法此前失效的问题。当前实现见 Package.ts#L235-L256export function setPackageInBuildGradle(config: PickExpoConfig, android, buildGradle: string) { const packageName getPackage(config); if (packageName null) { return buildGradle; } // 同时匹配赋值形式applicationId ...与传统调用形式applicationId ... const pattern new RegExp((applicationId|namespace)(\\s*\\s*|\\s)[].*[], g); return buildGradle.replace(pattern, $1$2${packageName}); } export async function getApplicationIdAsync(projectRoot: string): Promisestring | null { // ... // Match both the legacy method-call form (applicationId com.app) and the // Gradle assignment form (applicationId com.app) const matchResult buildGradle.match(/applicationId\s*?\s*[](https://link.gitcode.com/i/a1ed43e3f0f91980ada02c30e7b590b7)[]/); return matchResult?.[1] ?? null; }可以看到两处正则都通过\s*\s*读与(\\s*\\s*|\\s)写同时兼容方法调用与赋值两种 Gradle 语法并且写入时还一并处理了namespace。对应的回归测试位于 Package-test.ts其中包含getApplicationIdAsync解析com.helloworld与setPackageInBuildGradle改写my.new.app的用例。3.3 [iOS] 补充UIRequiresFullScreen在 iOS 27 的行为文档变更说明自 iOS 27 起UIRequiresFullScreen不再使应用退出窗口缩放resize相关说明也被加入 iPad 多任务警告文案。源码印证见 RequiresFullScreen.ts#L35 的注释As of iOS 27,UIRequiresFullScreenno longer opts an app out of resizing. It requests discrete...行为断言由 RequiresFullScreen-test.ts 覆盖验证UIRequiresFullScreen在 true/false 下的 Info.plist 输出。四、破坏性变更时间线升级前必读CHANGELOG 中标记 Breaking changes的条目按时间排列如下跨大版本升级时应逐一核对6.0.02023-02-03Google 登录与 Facebook 配置清理移除已弃用的expo.ios.config.googleSignIn.reservedClientId改用expo.ios.googleServicesFileIOSConfig.Google.getGoogleSignInReservedClientId更名为getGoogleSignInReversedClientIdIOSConfig.Google.setGoogleSignInReservedClientId更名为setGoogleSignInReversedClientId移除已弃用的 Facebook 类型与插件。7.0.02023-05-08classic updates 默认行为新增对config.updates.useClassicUpdates默认行为的支持。该版本还修复了updates.checkAutomatically缺失取值7.0.0 修复条目、任意平台默认按[dangerous]排序的 mod 执行顺序问题并把平台类型抽象化。7.4.02023-09-04彻底移除 classic updatesRemove classic updates配合 8.0.0-beta.0 中移除 classic updates 的 SDK 版本与发布渠道的后续清理。7.5.02023-09-15runtime version API 异步化getRuntimeVersion/getRuntimeVersionNullable被替换为getRuntimeVersionAsync/getRuntimeVersionNullableAsync。当前 utils/Updates.ts#L74-L116 中仍可见这两个异步函数getRuntimeVersionNullableAsync内部捕获异常并在EXPO_DEBUG开启时打印日志getRuntimeVersionAsync处理字符串版本、file:fingerprint保留字会抛错提示改用 fingerprint 策略与策略对象三种形态。10.0.02025-04-30scheme 语义收紧破坏性android.package不再出现在 scheme 列表中同时新增在配置 schema 中暴露ios.scheme与android.scheme。56.0.02026-05-05AndroidConfig.StatusBar替换为AndroidConfig.SystemBars这是最新一次破坏性变更源码印证见 SystemBars.tssetSystemBarsStyles会同时把android:statusBarColor与android:navigationBarColor设置为android:color/transparentSystemBars.ts#L9-L25withSystemBars插件检测到配置里仍存在androidStatusBar或androidNavigationBar时通过WarningAggregator.addWarningAndroid输出弃用警告分别指向expo-status-bar与expo-navigation-bar的插件配置。注意与 9.0.0 中的相关演进呼应getAppThemeLightNoActionBarGroup早已弃用并替换为不覆盖父主题的getAppThemeGroupsetSystemBarsStyles的parent正使用后者。五、重要新功能逐项解析57.0.32026-07-07ios.version/android.version覆盖真正生效修复Updates.getAppVersion、Updates.getNativeVersion与appVersion运行时版本策略忽略平台专属version的问题此前只配置ios.version/android.versionapp.json顶层无version的项目在这些 helper 的调用处会回落到package.json兜底或1.0.0。Updates.getAppVersion新增可选platform参数传入时优先使用平台覆盖不传则保持旧行为同时修复了Updates.getNativeVersion在 Android 上误用 iOS 版本的问题。当前实现 utils/Updates.ts#L32-L72 与描述完全对应getAppVersion先判断platform ios config.ios?.version、再判断platform android config.android?.version最后回落到config.version ?? 1.0.0getNativeVersion的 Android 分支使用AndroidVersion.getVersionName修复前是 iOS 分支逻辑iOS 分支输出version(buildNumber)、Android 输出version(versionCode)格式非法平台直接抛错。56.0.72026-05-20插件文件支持.cjs/.mjs/.ts/.cts/.mts扩展名同一个 PR 还带来两项改进加载/解析 config plugin 失败时透传loadModuleSync的更友好错误信息内部将插件解析对齐expo/config基于expo/require-utils并移除了resolve-from依赖。这与 9.0.3 → 9.0.4 → 11.0.0 的解析器演进一脉相承9.0.3 曾恢复从 package.json main 字段解析9.0.4 移除了对main入口的弃用警告11.0.0 改进了插件解析器的错误处理。56.0.52026-05-13intent filter 类型补全为 intent filter 类型补齐pathPrefix、pathSuffix、mimeType、pathPattern、pathAdvancedPattern与port字段与 IntentFilters.ts 中的IntentFilterType定义配套。56.0.02026-05-05ios.deploymentTarget配置支持新增通过ios.deploymentTarget设置最低 iOS 版本源码入口为 ios/DeploymentTarget.ts测试见 DeploymentTarget-test.ts。同版本还为URLScheme类型补齐CFBundleTypeRole并把模板中的com.google.gms:google-servicesGradle 插件升到4.4.4。55.0.72026-03-18setProvisioningProfileForPbxproj支持codeSignIdentity此前调用方只能硬编码iPhone Distribution新增可选参数后可显式指定代码签名身份。测试快照见 ProvisioningProfile-test.ts.snap。55.0.02026-01-21iOSLocalizable.strings的 locales 支持[iOS] 为Localizable.strings新增locales支持实现位于 ios/Locales.ts测试与快照见 Locales-test.ts移除newArchEnabled选项与 9.1.1 中默认启用 newArchEnabled构成完整生命周期maps 配置插件支持以main作为锚点。55.0.12026-01-22模板存储权限增加android:maxSdkVersion32针对 Android 13 不再授予存储权限的现实在模板中的存储权限声明上加上 maxSdkVersion 上限。11.0.02025-08-13Android 侧能力扩展支持用别名aliases构建 Activity支持android.predictiveBackGestureEnabled配置字段实现见 android/PredictiveBackGesture.ts插件解析器改进错误处理从android目录导出CodeMod、从utils/generateCode导出CodeGenerator供第三方包的 config-plugin 复用见 utils/generateCode.ts。10.1.0 / 10.1.22025-07应用名翻译与字符串安全10.1.0 新增 Android 应用名翻译配置插件10.1.2 修复本地化字符串含单引号导致构建失败的问题方式为在strings.xml中对字符串值整体加引号包裹测试见 Strings-test.ts。9.0.02024-10-22withDevelopmentTeam与解析器收紧新增withDevelopmentTeam修改 Apple 开发者团队 ID实现与测试见 ios/DevelopmentTeam.ts 与 DevelopmentTeam-test.ts修复引用库插件文件时的解析问题并整体收紧 config plugin 解析改进无效配置的报错信息glob7升级到glob10快照统一为 iOS deployment target 15.1。9.1.02025-04-04updates.useNativeDebug与桥接头清理支持updates.useNativeDebug修复 prebuild 中孤立的 bridging header 引用从默认插件中移除桥接头创建、改由模板提供react-native-maps插件在未安装且未提供 API key 时不再被应用iPad 方向仅在实际启用平板支持时才追加UISupportedInterfaceOrientations~ipad字符串资源标签值为空时抛出更具描述性的错误。9.0.15 / 9.0.172025-02/03updates 与版本配置增强9.0.15 新增updates.disableAntiBrickingMeasures支持对应 utils/Updates.ts 中的getDisableAntiBrickingMeasures9.0.17 允许version在 iOS 与 Android 分别覆盖57.0.3 的 helper 修复正是建立在该能力之上。8.0.0-beta.02024-04-17PrivacyInfo 插件落地新增 privacy info 配置插件实现见 ios/PrivacyInfo.ts修复.xcprivacy被误加进 build sources 而非 resources、以及插件会合并新旧 privacy info 的问题清理 classic updates 的 SDK 版本与发布渠道新增expo-updatesCLI 的runtimeversion:resolve命令。8.0.22024-04-24withPodfile插件新增withPodfile用于替代withDangerousMods执行 Podfile 相关操作源码见 withDangerousMod.ts 所在目录的插件基础设施。7.5.02023-09-15fingerprintExperimental运行时版本策略配合 8.0.0 中将其正式更名为fingerprint策略构成 EAS Update 指纹机制的演进路径。7.2.42023-06-30entitlements 忽略已有原生文件选项为 entitlements 求值新增忽略已存在的原生文件选项实现见 ios/Entitlements.ts。7.1.02023-06-13iOS 默认开启CADisableMinimumFrameDurationOnPhone并支持 React Native 0.72修复Target.findApplicationTargetWithDependenciesAsync把 framework target 标记为不可签名的问题。六、关键 Bug 修复汇总CHANGELOG 中修复类条目对 prebuild 用户影响最直接按主题归纳Gradle / 包名相关Android11 之前版本中包名改写多次收紧7.7.0 只改写带引号或带前缀的 Android 包名8.0.4 让is、in、fun等 Kotlin 关键字作为包名片段也能工作见 Package.ts 的replacePackageName限定替换策略Unpublished未发布修复 Gradle 赋值语法见本文 3.2 节8.0.6 修复 Android 状态栏translucent设置57.0.3 修复getNativeVersion在 Android 上误用 iOS 版本。manifest / schemeAndroid10.0.2在追加 scheme 前先确保 manifest 中存在有效的 intent filter——修复未提供scheme配置时 scheme 写不进 manifest 的问题8.0.5改进 Android manifest queries 建模package 变为可选、provider 变为数组ManifestQuery类型早在 7.6.0 引入10.0.0把android.package从 scheme 列表中移除。Info.plist / pbxprojiOS7.8.0ios.bundleIdentifier只写入主.pbxproj文件改用串行withXcodeProjectmod8.0.3修复 privacy info 插件把绝对路径写进.pbxproj9.0.12修复 Windows 上解析 iOS build scheme7.5.0DeviceFamily.ts修复使其适用于 Apple TV。运行时 / updates9.1.1 起newArchEnabled默认启用55.0.0 移除该选项——使用旧配置的用户升级后无需任何动作55.0.6 把androidStatusBar.backgroundColor与androidStatusBar.translucent弃用为 no-op56.0.0 的SystemBars插件会进一步对残留配置给出警告。Windows 兼容性三连9.0.x 集中修复9.0.6 避免在 glob 模式中做路径字符改写9.0.102024-11-20支持 Windows 下用嵌套模块说明符解析 config plugin9.0.12 支持 Windows 上解析 iOS build scheme。七、第三方依赖与内部重构CHANGELOG 的 Others与 3rd party library updates分区记录了影响面较广的基础设施变化glob9.0.0 从glob7升级到glob1054.0.3 再升级到glob^13.0.0semver7.2.2 升级 semver8.0.0-beta.0 将 semver 从 7.5.3 升到 7.5.4getenv10.0.3 升级到getenv2.0.0以支持大写的布尔型环境变量utils/Updates.ts中即使用boolish(EXPO_DEBUG, false)读取调试开关依赖移除/替换55.0.3 移除slash依赖56.0.7 用expo/require-utils替换resolve-from7.8.2 补回缺失的slugify依赖7.2.0 更新xml2js7.2.1 移除已弃用的withPackageManifest插件以消除 Android 构建警告消息风格10.0.3 移除警告/错误文案中的 PleaseJS 引擎6.0.0 起默认 JS 引擎切换为 Hermes并宣布expo.jsEngineandroid/gradle.properties弃用、改用hermesEnabled。八、与 React Native 版本的支持对应CHANGELOG 中多次以Added support for React Native X形式声明兼容性可作为选型与升级依据config-plugins 版本日期React Native 支持6.0.02023-02-03RN 0.71.x10.0.3 前的 6.0.0 修复条目#20799/#208327.1.02023-06-13RN 0.727.8.02023-12-12RN 0.73.0新架构开关的演进也在其中9.1.1 默认启用newArchEnabled55.0.0 移除该选项——从源码结构看这意味着当前版本的 prebuild 产物不再需要也不接受该配置项。九、升级与验证建议结合 CHANGELOG 与仓库实际内容给出可操作的验证方式升级前对照本文第四节把你跨越的每个大版本尤其 6.0.0、7.4.0/7.5.0、10.0.0、56.0.0的破坏性条目与自己的app.json、自定义插件调用核对若自定义插件调用了IOSConfig.Google.get/setGoogleSignIn*ClientId、AndroidConfig.StatusBar或getRuntimeVersion旧签名需先迁移。升级后重新执行 prebuild用 git diff 对比生成的android/、ios/产物确认 SystemBars 透明栏、RCTMetroPort键若使用 Unpublished/后续正式版本、strings.xml引号包裹等符合预期。排查插件解析问题设置EXPO_DEBUG1必要时加EXPO_CONFIG_PLUGIN_VERBOSE_ERRORS1运行构建观察 56.0.7 之后透传出的loadModuleSync错误信息。回归验证包内已有大量单元/快照测试可作行为基准如 android/tests、ios/tests与 utils/tests例如 Updates-test.ts、codeMod-test.ts阅读它们的期望值可快速确认某个 mod 的精确输出格式。CHANGELOG 顶部长期保留Unpublished分区意味着在两个正式版本之间仓库中的这份记录会先于发布累积变更阅读最新版本号时留意该分区可以提前获知withMetroPort这类尚未发版的能力何时进入你的依赖。【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考