expo/metro-runtime 完全解析Expo 生态中高级 Metro 打包特性的运行时注入原理与接入指南【免费下载链接】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/expoexpo/metro-runtime是 Expo 开源仓库中负责“运行时补全”的关键基础包当代码经由 Metro 打包器以高级特性如 React Server Components、Window Location 语义、开发态 HMR 错误追踪执行时它会在 bundle 最前端注入必要的运行时逻辑让产物在 Android、iOS 与 Web 上行为一致。读完本文你将掌握该包的安装与导入方式、它被 Metro 自动提升为首个模块的机制以及它内部实际执行的五类初始化工作window.location polyfill、fetch 相对路径包装、RSC runtime、开发态日志捕获、Promise 拒绝追踪并能对照源码理解每项能力的作用边界。包的定位为“Advanced Metro 特性”补充运行时Injects runtime code required for advanced Metro bundling features in the Expo ecosystem.这句来自 官方 README 的概述划定了它的全部职责Metro 本身只负责“打包”而打包产物中某些运行时能力例如浏览器语义的window.location、面向开发服务器的日志上报、RSC 客户端运行时并不天然存在于原生 JS 引擎中。expo/metro-runtime的存在价值就是在应用 bundle 的最早执行时机把这些能力“注入”进去。这一点在包元数据中也有直接体现。查看 package.jsonsideEffects: true——明确告知打包器该模块的导入具有副作用导入即执行注入逻辑因此不能被 tree-shaking 或 import 排序机制误删或挪动入口main: build/index.js与源码映射expo-source: ./src/index.ts——开发工具链在调试时会直接解析到 TS 源码对外额外暴露./rsc/runtime.js与./rsc/runtime两个子路径专门用于 RSCReact Server Components场景依赖集中于开发基础设施expo/log-boxExpo 的 LogBox 日志 UI、anserANSI 转义码解析、pretty-format日志美化、stacktrace-parser错误堆栈解析、whatwg-fetchfetch 标准 polyfill。在 CHANGELOG.md 中可以持续追踪该包演进当前仓库内版本为 57.0.8它紧密跟随 Expo SDK 迭代节奏发布。安装与导入三步完成接入第一步安装依赖yarn add expo/metro-runtime第二步在初始 bundle 中导入将该包导入到整个应用最先被执行的模块中例如入口文件App.jsimport expo/metro-runtime;之所以强调“初始 bundle”是因为注入逻辑polyfill 安装、全局对象覆盖必须早于任何业务代码的首次执行才有意义——若某个业务模块在 import 阶段就读取了window.location那么注入必须在它之前完成。第三步交给 Metro 自动提升官方文档特别说明expo/metro-config会自动将这个 import 移动为 bundle 中的第一条语句。这意味着你无需手工保证它在文件里的物理位置只需保证它在“某个会在启动路径上被加载”的模块中即可。这也解释了为什么该包被设计为“副作用导入”而非“具名导出 API”——绝大多数用户永远不需要 import 它的任何具名成员。一个重要的例外expo-router 用户无需安装README 明确提示expo-routerusers do not need to install this package, it is already included.如果你使用expo-routerExpo 官方的文件路由方案该依赖已经被间接包含直接使用即可如果你在使用纯 Expo 应用非 expo-router并依赖 RSC、相对路径 fetch 等高级能力则应按上述步骤手动接入。入口做了哪些事逐行解读src/index.ts包的运行时主入口是 src/index.ts全部逻辑不过二十余行但每一行对应一类关键职责import ./location/install; // ① 安装 window.location 语义 import expo/metro-runtime/rsc/runtime; // ② 引入 RSC 客户端 runtime if (__DEV__) { require(./metroServerLogs).captureStackForServerLogs(); // ③ 服务端/编译日志捕获 require(./promiseRejectionTracking).enablePromiseRejectionTracking(); // ④ Promise 拒绝追踪 // ⑤ 接入 expo/log-box暴露清空日志的全局方法 globalThis.__expo_dev_reset_errors require(expo/log-box/LogBox).default.clearAllLogs; }观察可知其分层策略跨环境必需的能力location、RSC runtime无条件执行仅在开发态有用的诊断能力日志堆栈捕获、Promise 拒绝追踪、LogBox 重置钩子通过__DEV__包裹从而保证生产 bundle 不携带额外诊断开销。设计兼容.native.ts与.ts双实现注意上面 import 路径没有.native后缀——Metro 的 platform 解析会按平台选择 install.native.ts 与install.ts。Web 端的 install.ts 几乎为空实现install()与setLocationHref()均为空函数因为浏览器本身已提供标准window.location而真正有分量的原生端实现集中在Location.native.ts与install.native.ts中。这正是“同一套代码跨 Android/iOS/Web 运行”的 Expo 式工程解法。原生端注入的两大核心Location 与 fetch一个遵循 Web 规范的 Location 实现Location.native.ts 在原生 JS 引擎中模拟了 Web 的window.location对象。它基于URL构造实现细节刻意追求与浏览器语义一致hash、host、hostname、href、pathname、port、protocol、search均提供只读 getter对任何写入行为set、assign、replace、hash修改等统一抛出DOMExceptionNotSupportedError禁止在原生端修改 URL 片段——这一约定对齐了 Web 规范中Location接口的LegacyUnforgeable属性限制reload()是唯一“有实际效果”的方法且实现了双分支降级开发态调用 React Native 的DevSettings.reload()触发原生 fast refresh 重载生产态Expo SDK 51走globalThis.expo.reloadAppAsync()两者皆不可用时才抛出异常。文件头部的版权注释还透露了实现渊源——该实现移植/参考了 Deno 对 WorkerLocation 语义的封装Copyright 2018-2023 the Deno authors即它的目标是WinterCGWeb-interoperable Runtimes Community Group兼容让运行在不同 JS 引擎上的 Expo 应用对外暴露一致的 Web 标准全局对象。注入逻辑与 origin 决策链真正把 polyfill 装进运行时的函数位于 install.native.ts其导入顺序本身就是一份“运行时初始化清单”import react-native/Libraries/Core/InitializeCore; // 先初始化 RN 核心全局 import whatwg-fetch; // 先装 fetch/Headers/Request import expo; // 确保 URL 全局可用 import Constants from expo-constants; import { getBundleOrigin } from expo/internal/bundle-origin;该文件注释明确警告必须保证 React Native 核心全局变量先于本包初始化避免依赖不稳定的getModulesRunBeforeMainModule机制这一约定与expo/winter/runtime.native.ts中 Expo Winter runtime 的初始化顺序相互呼应。随后是 origin 决策逻辑getOrigin()开发态优先读取expo/internal/bundle-origin提供的 dev server 地址即当前 JS bundle 是从哪个 HTTP 源下载的因为此时应“跟随 bundle 来源”发起请求生产态固定使用 app config 中extra.router.origin显式配置否则回退到 release 构建时自动写入的extra.router.generatedOrigin当 app 在原生端以非 HTTP 方式加载且未配置任何 origin 时getBaseUrl()返回null此时不做任何注入——这是有意的宽容设计让相对 URL 请求“按原样失败”而不是抛出不友好的Invalid URL异常。让原生 fetch 支持相对 URL配合 Location 注入同一文件还通过wrapFetchWithWindowLocation包装了全局fetch对应单测 覆盖了这一行为当请求是/path开头的字符串、或含url字段的 RequestInit 对象时将其与window.location.origin拼接成绝对 URL 再发起请求。包装函数使用Symbol.for(expo.polyfillFetchWithWindowLocation)打标避免重复包装。这样一来原生端代码也能像 Web 一样书写“根路径相对请求”。整个 Location fetch 注入受配置开关控制仅当extra.router.origin ! false时才启用 polyfill若用户显式将 origin 设为false则跳过 Location 注入、仅保留 fetch 直接赋值。RSC 子入口rsc/runtime.js入口中的import expo/metro-runtime/rsc/runtime指向 rsc/runtime.js该子路径也在 package.json 的exports中被单独声明。它承载的是 Expo 在 Metro 之上支持React Server ComponentsRSC所需的客户端运行时。对普通原生应用而言这段代码是透明无感知的只有当你使用expo-router的 RSC / Server Actions 能力、或直接开启 RSC 渲染时这份 runtime 才会真正承担序列化协议与请求流对接的职责——它同样是“为了让高级 Metro/React 特性跑起来而注入的运行时”这一包定位的直接体现。开发态的诊断增强Metro 服务端日志的堆栈捕获metroServerLogs.native.ts 对 React Native 的HMRClient.log做了包装目标是把“来自 Metro 服务端如编译错误、远端警告的日志”在设备端补上可读的堆栈上下文仅拦截error级别源码注释中warn被注释掉即暂不处理 warning若日志项带有preventSymbolication: true直接跳过——这专门服务于编译错误场景避免符号化失败或在 Metro 与设备端被重复打印实现参考了 React Native 上游HMRClient.js的相关逻辑对没有错误堆栈的日志合成一个“调用点堆栈”captureCurrentStack()使用无名 Error 捕获避免污染堆栈名称对含组件栈的日志通过特征正则识别新旧两代组件栈格式补上 React 的captureOwnerStack()作为 owner 栈否则将已有 stack 字段显式塞入 data 数组防止被pretty-format吞掉。这保证了开发者在 Expo Go / dev client 中看到编译或运行时错误时能定位到真正出错的组件与代码行而不是面对一串无上下文的服务端消息。Promise 拒绝追踪与 LogBox 钩子promiseRejectionTracking.native.ts与index.ts同目录提供enablePromiseRejectionTracking()用于在开发态尽早暴露未被处理的 Promise rejection源码注释标注为上游 React Native 待修复问题的临时方案预期在 RN 0.82 移除。与此同时入口还把expo/log-box/LogBox的clearAllLogs挂到globalThis.__expo_dev_reset_errors供 Expo 工具链在“重置错误状态”时调用。错误堆栈解析开发态依赖的堆栈解析逻辑集中在 ExceptionsManager/parseErrorStack.ts基于stacktrace-parser将原始堆栈字符串解析为结构化 frame并对column做-1修正因为 Metro 的 bundle 帧与用户源码存在一列的偏移注释中示例帧形如http://localhost:8081/index.bundle?platformwebdevtruehotfalse同时为 frame 增加collapse标记能力以支持折叠无意义的内部帧。在 Expo 仓库中的完整图景expo/metro-runtime不是孤立存在的。把它放回仓库整体坐标系中它的上下游关系非常清晰下游消费方expo/metro-config自动将其 import 提升为 bundle 首条与expo-router作为内置依赖预置兄弟依赖expo/log-box日志 UI 与clearAllLogs、expo-constants/expo本体提供 manifest 与 URL 基础设施同类基建packages/expo中的 Winter runtime 与其共享“跨端标准全局”的初始化次序约定。如果你想在仓库里观察它的真实消费方式可以从expo/metro-config源码入手搜索对expo/metro-runtime字符串的处理逻辑理解“提升为首条 import”的具体实现也可以基于 expo-template-blank 或 expo-template-default 这类模板创建新项目检查打包产物的首行 import 来验证其行为。小结与使用建议总结expo/metro-runtime的核心要点关注点结论职责在 bundle 最前端注入高级 Metro/React 特性所需运行时安装方式yarn add expo/metro-runtime并在初始 bundle如App.js中import expo/metro-runtimeimport 排序expo/metro-config会自动提升为首条执行expo-router 用户无需手动安装已内置跨端策略.native.ts提供完整 polyfillWeb 端为空实现原生端注入内容只读window.location、支持相对 URL 的fetch、RSC runtime开发态额外能力HMRClient 服务端日志堆栈捕获、Promise 拒绝追踪、LogBox 重置钩子使用建议普通 Expo expo-router 应用通常“零配置”即受益于此包若你的应用绕开了 expo-router但仍希望获得 Web 风格 Location 语义、相对路径 fetch 或 RSC 能力则按本文三步完成手动接入。生产 bundle 无需关心__DEV__内的逻辑——它们不会进入发布产物。【免费下载链接】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），仅供参考