深入解析 babel-preset-expoExpo 通用应用 Babel 编译管线与全参数配置指南【免费下载链接】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在 Expo项目根目录的架构中babel-preset-expo是贯穿 iOS、Android、Web 与服务器端渲染全链路的 Babel 预设它以react-native/babel-preset为基线把 tree shaking、按需拆包、React Server Components、Hermes 字节码编译、React Compiler、Reanimated / Worklets、Expo DOM Components、SSR 与高级死代码消除等能力统一收口到一次编译中。读完本文你将掌握该预设的调用方约定Babel caller 契约、全部顶层与平台专属配置项的行为语义、配置优先级规则以及如何借助本仓库源码与测试理解它在 Metro、Webpack 等打包器中的真实取舍进而在任何 React Native / Expo 项目中精准配置与排障。一、它是什么可无缝替换 RN 默认预设的通用编译层根据 包说明文档babel-preset-expo扩展了 React Native 默认预设react-native/babel-preset并额外提供Tree shaking借助 ESM 语义与disableImportExportTransformBundle splitting / 按需拆包配合lazyImports与静态 ESMReact Server ComponentsRSC相关的服务端 action、loader、metadata 插件Hermes 编译hermes-v0/hermes-v1双版本配置族高级死代码消除typeof window、Platform.OS、process.env.NODE_ENV、__DEV__等常量折叠Reanimated / Worklets 的自动 Babel 插件注入Expo DOM Components 与 WebView 降级预设服务端渲染SSR关键定位是它可作为react-native/babel-preset的drop-in 替代品应用在任何 React Native 项目里。从本仓库的 package.json 看当前版本为57.0.5入口为build/index.js运行时可选的peerDependencies包括babel/runtime、expo、expo-widgets与react-refresh后三者为可选不会阻塞安装。仓库内部大量示例应用都以它为默认 Babel 预设例如 bare-expo 的 babel.config.js、native-component-list、router-tester 与 test-suite 等可直接作为工程化参照。二、Expo Bundler SpecBabel Loader 的 caller 契约要使该预设正确工作打包器/Babel Loader 必须在调用时通过caller传入若干元数据。文档将这套要求称为Expo Bundler Spec Compliance适用于任何声称面向 universal React/Expo 项目的打包器。预设主入口在 src/index.ts其中通过api.caller(...)读取这些字段具体读取逻辑集中定义于 src/common.ts 的getBundler/getPlatform/getEngine/getIsDev/getIsServer/getStaticESM等辅助函数。1.caller.platform目标平台platform表示本次打包的目标平台。若未定义当bundler为webpack时默认回退为web文档注明该行为是临时的未来版本将直接抛错。值说明ios运行于 iOS 设备android运行于 Android 设备web运行于 Web 浏览器在 common.ts 中getPlatform的实现是优先取caller.platform否则当 bundler 判定为webpack时回退为web。2.caller.bundler打包器身份bundler表示正在生成 JS bundle 的打包器名称。若未定义会先检测是否使用了babel-loader——是则视为webpack否则默认视为metro。值说明metro使用 [Metro] 打包webpack使用 [Webpack] 打包实际判定逻辑见 common.ts优先取caller.bundler随后对caller.name babel-loaderexpo/webpack-config、Next.js 10 等以及caller.name next-babel-turbo-loaderNext.js 11返回webpack其余一律假定 Metro。注common.ts中还读取大量其他 caller 字段用于驱动编译策略例如engineHermes 还是默认 JSC、isServer、isReactServer、isNodeModule、supportsStaticESM、isHMREnabled、supportsReactCompiler、baseUrl、metroSourceType与babelRuntimeVersion等。生产环境还要求打包器显式传入isDev: false见getIsProd否则常量内联等优化不会生效。三、源码视角编译管线是如何被选型的在主入口 src/index.ts 中预设最终按 Babel 约定把presets组装为三段module-transforms 预设放在presets数组首位因 Babel 逆序执行而最后运行负责import/export → CommonJS变换、运行时辅助函数babel/plugin-transform-runtime以及懒加载策略见 module-transforms.ts。引擎预设根据平台/引擎选取其一isDomComponentExpo DOM ComponentsWebView 场景→ webview.tsWeb 或任意 SSR 环境现代引擎→ web.ts否则按unstable_transformProfile在 Hermes v1 / Hermes v0 间切换见 hermes-v1.ts、hermes-v0.ts。Expo/React 专属预设configs/expo.ts注入 React Compiler、codegen、react-refresh、expo-router、RSC/server 系列、inline manifest、inline env vars、Reanimated/Worklets 等插件其下再套 configs/react.ts 完成 JSX 变换。此外顶层还统一挂载 Flow/TS 类型剥离片段与语法插件见 syntax.ts含 Hermes parser、export-default-from、动态import()、空值合并与可选链语法支持。代码注释特别强调模块变换预设必须最后执行以保证import/export变换在所有其他插件处理完代码之后进行而 Flow/TS 类型剥离必须先于 class-properties 类插件。这一“三段式 平台化配置族”的结构正是理解后面所有配置项作用的底层框架。四、Options全部顶层配置项逐条精讲以下所有选项都在babel.config.js中以[babel-preset-expo, { ... }]形式传入。类型签名可对照 src/index.ts。4.1react-compilerReact Compiler 配置设置要传给babel-plugin-react-compiler的选项设为false则关闭该插件。自 SDK 51 起还需要在app.json中开启experiments.reactCompiler: true才能真正激活。[ babel-preset-expo, { react-compiler: { sources: (filename) { // Match file names to include in the React Compiler. return filename.includes(src/path/to/dir); }, }, }, ];从 configs/expo.ts 的实现可补充四个关键行为帮助你在源码层面掌握其触发条件与默认值触发门槛需要caller.supportsReactCompiler即experiments.reactCompiler为真同时跳过 node_modules、跳过所有服务端/SSR 场景作者注释认为编译器对 RSC 收益不明且希望避免水合错误并允许以react-compiler: false在平台层单独退出。默认 targettarget: 19即以 React 19 语义编译。开发环境差异environment.enableResetCacheOnSourceFileChanges在非生产为truepanicThreshold在开发时不设可输出诊断生产强制为NONE编译失败不 panic。内置退出指令除用户自定义外预设总会保留use no memo、use no forget以及内部用于 Swift UI Widget 的widget指令避免它们被用户覆盖后失效。包内专门提供 compiler.test.ts 及快照 compiler.test.ts.snap 对编译结果做回归校验。4.2minifyTypeofWindow折叠typeof window判断设置为true时将代码中的typeof window检查做编译期求值例如if (typeof window object)在客户端被改写为if (true)。当引用的第三方库在原生端或服务端“mock”了 window 对象时这一能力尤其有用。[ babel-preset-expo, { // If your native app doesnt polyfill window then setting this to false can reduce bundle size. native: { minifyTypeofWindow: true, }, }, ];默认值服务端环境为true客户端环境为false为兼容旧的浏览器 polyfill 与 Web Worker 保留真实判断。源码 configs/expo.ts 进一步揭示了默认取值的细节实际生效值由minifyTypeofWindow ?? isServerEnv决定即服务端环境天然开启而 Web Worker 场景目前尚未传递元数据因此对 Web 客户端暂时停用了该项默认优化避免误折叠。折叠由define-pluginplugins/define-plugin.ts以 inline 常量形式注入。4.3reanimated自动注入 Reanimated 插件boolean默认true。当工程安装了react-native-reanimated时该预设会自动追加其 Babel 插件设为false可禁用。// 显式关闭示例 [ babel-preset-expo, { reanimated: false }, ];4.4worklets自动注入 Worklets 插件boolean默认true。当使用独立的react-native-worklets、或react-native-reanimated4 时预设会自动追加react-native-worklets/plugin设为false可禁用。源码中的注入策略值得注意见 configs/expo.ts它会先尝试解析react-native-worklets/plugin只有在该模块不存在时才回退到react-native-reanimated/plugin。换言之Reanimated 4 的 worklets 管线优先于旧版 reanimated 插件两条路径不会同时叠加。4.5jsxRuntimeJSX 运行时策略classic | automatic默认automatic向下传给babel/plugin-transform-react-jsx。automatic自动将 JSX 转换为 JS无需在每个文件里import React from react。启用后请按 React 官方 JSX 新变换升级指南同步调整 ESLint 等工具的配置否则会收到告警。classic不自动导入任何内容凡使用 JSX 的文件必须显式导入 React。[ babel-preset-expo, { jsxRuntime: classic, }, ];在 configs/react.ts 中classic且开发模式下会改用babel/plugin-transform-react-jsx-development作者注明classic仅为遗留场景保留非classic时额外把pure置为!dev生产构建生成带纯注解的调用便于后续压缩与 tree shaking。4.6jsxImportSource自定义 JSX 自动导入来源string默认react。指定 automatic 运行时下 JSX 函数如jsx、jsxs、Fragment的导入来源。[ babel-preset-expo, { jsxRuntime: automatic, jsxImportSource: react, }, ];该选项同样透传给babel/plugin-transform-react-jsx仅当jsxRuntime为automatic时生效。4.7lazyImports按需惰性求值 import将 Babel 编译后的import改为“首次使用到其绑定变量时才求值”可以显著缩短首屏加载耗时——因为部分依赖尤其无副作用者并不需要在启动时立即执行。注意仅当disableImportExportTransform为false时才生效。在 Android/iOS 上disableImportExportTransform默认false而在 Web 上默认true为支持 tree shaking因此该选项主要作用于原生端。lazyImports的取值语义值行为null默认交由react-native/babel-preset自行处理false不做任何模块的惰性初始化true除本地导入如./foo、有副作用的特定 Expo 包以及 Babel commonjs 文档列出的两类例外外全部惰性初始化Arraystring交给babel-plugin-transform-modules-commonjs的lazy处理(string) boolean同上由自定义谓词函数决定每个模块是否惰性如果你自行实现谓词还可以通过const lazyImportsBlacklist require(babel-preset-expo/lazy-imports-blacklist);取得一个有副作用的 Expo 包名单一个Set。[ babel-preset-expo, { lazyImports: true } ],源码 module-transforms.ts 完整实现了该策略内置两张名单 ——expo-lazy-imports见 utils/expo-lazy-imports.ts当前包含expo、expo-asset、expo-task-manager注释明确它们可能有副作用绝不应被惰性初始化与rn-lazy-importsreact-native系总是惰性初始化。命中 Expo 名单返回false保持立即求值命中 RN 名单返回true当配置为true时对本地路径含./返回false。同时该 transform 以strict: false、strictMode: false阻止注入use strict并允许顶层this不重写确保与原生模块运行时兼容。4.8disableImportExportTransform关闭 import/export 转换传true可关闭“把import/export转为module.exports”的转换。文档强烈建议避免直接设置该属性如果使用 Metro应改设experimentalImportSupport: true保证整条管线被正确配置。// metro.config.js config.transformer.getTransformOptions async () ({ transform: { // Setting this to true will automatically toggle disableImportExportTransform in babel-preset-expo. experimentalImportSupport: true, }, });当属性为undefined默认时会依据打包器设置的caller.supportsStaticESM自动决定。直接显式设置的示例[ babel-preset-expo, { disableImportExportTransform: true } ],源码 index.ts 展示了自动推导逻辑Web 平台取supportsStaticESM ?? isWebpack仅在 Webpack 场景默认关闭转换因为 Metro 当前不支持 tree shaking非 Web 平台取supportsStaticESM ?? false。此外当该选项开启时configs/expo.ts 还会追加detect-dynamic-exports插件用于动态导出检测。4.9unstable_transformProfileJS 引擎编译档位用于切换react-native/babel-preset所基于的引擎预设默认 JSC 风格或 Hermes 风格。Expo SDK 50 及以上会依据app.json中的jsEngine选项自动设置通常无需手写。源码中的可用值与取值映射见 index.ts 与类型定义为值效果default非 Hermes 引擎对应默认native编译档位hermes-v0旧版 Hermes 目标Hermes v0 配置族hermes-stableHermes 稳定目标走 Hermes v1 配置族hermes-canaryHermes canary 目标走 Hermes v1 配置族若未显式设置且目标非 DOM Component预设按engine hermes ? hermes-stable : default推导。Hermes v1 配置族会补上 class-properties、private methods、private properties 等变换这些在 hermes-v1 预设中缺失见 src/index.ts 的注释并附带多个针对旧 Hermes 语法修复的插件如 fix-hermes-v1-async-arrow-non-simple-params.ts、fix-hermes-v1-class-in-finally.ts。包的测试目录中 hermes-bytecode.test.ts 与 jsc-bundle.test.ts 覆盖了两种引擎的产物验证。4.10transformImportMeta转换import.meta启用将import.meta转换为globalThis.__ExpoImportMetaRegistry的变换。默认true。注意若 JS 引擎原生支持import.meta该变换可能干扰原生实现。实现位于 plugins/import-meta-transform-plugin.ts并由 configs/expo.ts 依据transformImportMeta ! false决定是否注入 polyfill 行为。4.11enableBabelRuntimeBabel runtime 辅助该选项控制 Babel 运行时辅助函数的注入方式默认按 caller 上报的babelRuntimeVersion或本包 peer 范围内babel/runtime版本解析显式传字符串可固定版本传false可整体禁用babel/plugin-transform-runtime。在 module-transforms.ts 中只要它不为false就会启用babel/plugin-transform-runtimehelpers: true, regenerator: trueHermes v0 场景无 regenerator 需求。此外当 Metro 上报metroSourceType script时脚本型入口无法注入依赖预设会自动把该选项降为false见 index.ts。五、Platform-specific options平台级差异化配置所有选项都可放入平台专属对象native与web中从而让不同平台使用不同取值。例如只想在 Web 上应用disableImportExportTransform[ babel-preset-expo, { // Default value: disableImportExportTransform: false, web: { // Web-specific value: disableImportExportTransform: true, }, }, ];优先级规则平台专属配置高于顶层配置。完整的平台维度不止两个——从类型定义 src/index.ts 可以看到除顶层外还支持web、native、tvos、macos、ios、android六组覆盖面。合并逻辑见getOptionssrc/index.tsweb平台取web层其余平台先取native层随后若存在更细的tvos/macos/ios/android覆盖则在其上继续叠加。因此示例中native.minifyTypeofWindow只影响所有原生平台而android.xxx可进一步对 Android 特化。六、实战配置速查与验证6.1 最小可运行配置对一个纯原生iOS/AndroidExpo/RN 工程最精简配置即一行预设module.exports function (api) { api.cache(true); return { presets: [babel-preset-expo], }; };由于所有选项都有默认值且大部分按 caller 自动推导platform、bundler、engine、isDev、supportsStaticESM等日常项目几乎无需额外参数想使用 React Compiler 时追加experiments.reactCompilerapp.json与react-compiler配置即可。6.2 从 API 变化追踪能力演进该包维护了独立 CHANGELOG.md升级 SDK 前可先核对其中 breaking change包级单测src/tests覆盖了如下值得关注的场景可作为“配置是否生效”的验证入口index.test.ts预设整体输出与默认组合platform-shaking.test.tsPlatform.OS等平台裁剪内联react-refresh.test.tsFast Refresh 开关metro-uniformity-matrix.test.tsMetro 各平台变换一致性矩阵minify-sanity.test.ts常量内联/压缩健全性jsx-import.test.tsJSX runtime 与 importSourceobject-rest-spread.test.ts 等语法覆盖用例示例样本位于 samples。运行方式在包目录下pnpm testJest见 package.json 的scripts.test或用pnpm lint/pnpm typecheck做静态校验。七、总结babel-preset-expo的价值不在于“又一个 Babel 配置集合”而在于它把平台、引擎、打包器三个正交变量收敛到一套声明式 API通过 caller 契约感知platform/bundler通过引擎档位选择 Hermes v0/v1 或 Web 变换族通过顶层 web/native/ios/android等多层选项实现粒度化定制。理解 src/index.ts 的组装顺序与 configs 的分工后你既能放心地在自定义 RN 工程中把它作为 drop-in 替代也能在遇到编译异常时快速定位是模块变换、引擎预设还是 Expo 专属插件在起作用。【免费下载链接】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），仅供参考