@expo/metro-runtime 完全解析：Expo 生态中高级 Metro 打包特性的运行时注入原理与接入指南

@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/expo

@expo/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.json：

• "sideEffects": true——明确告知打包器该模块的导入具有副作用（导入即执行注入逻辑），因此不能被 tree-shaking 或 import 排序机制误删或挪动；
• 入口main: build/index.js与源码映射"expo-source": "./src/index.ts"——开发工具链在调试时会直接解析到 TS 源码；
• 对外额外暴露./rsc/runtime.js与./rsc/runtime两个子路径，专门用于 RSC（React Server Components）场景；
• 依赖集中于开发基础设施：@expo/log-box（Expo 的 LogBox 日志 UI）、anser（ANSI 转义码解析）、pretty-format（日志美化）、stacktrace-parser（错误堆栈解析）、whatwg-fetch（fetch 标准 polyfill）。

在 CHANGELOG.md 中可以持续追踪该包演进（当前仓库内版本为 57.0.8），它紧密跟随 Expo SDK 迭代节奏发布。

安装与导入：三步完成接入

第一步：安装依赖

yarn add @expo/metro-runtime

第二步：在初始 bundle 中导入

将该包导入到整个应用最先被执行的模块中，例如入口文件App.js：

import '@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-router（Expo 官方的文件路由方案），该依赖已经被间接包含，直接使用即可；如果你在使用纯 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修改等）统一抛出DOMException（NotSupportedError），禁止在原生端修改 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），即它的目标是WinterCG（Web-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 Components（RSC）所需的客户端运行时。对普通原生应用而言这段代码是透明无感知的；只有当你使用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?platform=web&dev=true&hot=false），同时为 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-runtime'
import 排序	expo/metro-config会自动提升为首条执行
expo-router 用户	无需手动安装，已内置
跨端策略	.native.ts提供完整 polyfill，Web 端为空实现
原生端注入内容	只读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