一个周五下午收到反馈：用 Safari 打开线上某个页面白屏，控制台只有一行红字——ReferenceError: Can't find variable: React。同一个页面Chrome 一切正常。

这行报错看起来平平无奇，但顺着它挖下去。牵出了一条完整的链路：一个“减小首屏体积”的常见架构选择，如何在特定条件下把整站带崩；还有一个更反直觉的事实——我们的前端错误监控，恰恰监控不到这类最严重的崩溃。

这篇文章复盘整个排查过程，并给出一套不推翻现有架构、可直接复制的容灾方案。为方便讨论，下文把出问题的应用称为“某单页应用”。它把 React 等基础库通过 CDN 外置。

至于现象，只有 Safari 白屏，一行 ReferenceError

至于现象很干净。Safari 打开白屏，控制台就一行 Can't find variable: React；Chrome、Firefox 正常。

第一反应很容易是“Safari 兼容性问题”，接下来开始翻 Safari 的各种坑。但先别急着甩锅浏览器——这一步的误判会让你在错误的方向上耗很久。

至于根因，React 被“外置”到了 CDN

为了减小主 bundle、复用 CDN 缓存。很多项目会把 React 全家桶从打包产物里“外置”，改成运行时从 CDN 以全局变量的形式加载。典型配置是这样：

// vite.config.ts
export default defineConfig({
至于build，{
rollupOptions: {
external:,output: {
globals: { react: 'React','react-dom': 'ReactDOM' },},},},})

再配合一个 CDN 注入插件。最终 HTML 里大致长这样：

这套方案的效果是：编译后所有 import React from 'react' 都被 成引用全局 window.React。代价也随之而来——页面能否运行，强依赖那个 CDN 脚本先于主 bundle 执行成功。按理说，

而当时的实现。既没有 onerror也没有备用源、更没有就绪校验。一旦这个 CDN 脚本加载失败、被拦截或超时window.React 就不存在主 bundle 一执行到 React.xxx 立刻抛 ReferenceError整页白屏。

为什么偏偏是 Safari？先厘清一个误区

Safari 的 Can't find variable: X 和 Chrome/Firefox 的 X is not defined其实是同一个错误,只是不同引擎的措辞不同。其实，这压根不是 Safari 独有的 bug。

真正的触发点是“CDN 脚本没能在主 bundle 之前就绪”，这在任何浏览器、任何弱网或被拦截的场景下都可能发生。Safari 使用者更常安装内容拦截器/隐私保护插件，命中率或许略高；但监控数据显示，Chromium 系一样大量中招。

经验一：别被“只有某浏览器复现”带偏，先分清这是“浏览器 bug”还是“通用问题的浏览器措辞差异”。

反转的观点是，错误监控里这个崩溃查不到

按常规套路。去错误监控网站搜 React is not defined 和 Can't find variable: React. 结果：0 条.

0 条不等于没发生。老实说，

这里藏着一个监控盲区：

• Sentry 等前端错误监控 SDK 通常打包在主 bundle 内。在应用入口处初始化，
• 而 React 全局缺失时主 bundle ,监控 SDK 的初始化代码根本还没轮到执行。
• 于是最严重的那类崩溃.

说到反证也很有力。在同一个“全局依赖缺失”家族里那些发生在{useEffect} is not defined,{jQuery} is not defined,某 3D 库 {is not defined})——在监控里比比皆是。其实，因为它们发生时主 bundle 已经跑起来了,SDK 已经初始化。

flowchart TD
A --> B
B --> C
C --> D
D --> E
C --> F
F --> G
G --> H

任何 “监控 SDK 随主 bundle 加载” 的前端监控，都存在这个结构性盲区——它抓不到 “应用还没起来就崩了”的情况。话说回来，

一个容易被忽略的细节：措辞差异会撕裂告警

拆成两个独立 issue.

容灾这方面。四层加固

不推翻现有架构，只在 “资源加载层 + HTML 入口” 做冗余和观测,主源正常时零副作用。下面按 “观测 → 回退→受控串行加载 → 就绪兜底” 的顺序展开—第二层是我踩过的坑。第三层才是真正解，我把弯路一并写出来因为它比 “直接给答案” 更有价值。老实说，

再看第一层，独立于 bundle 的探针,先把盲区补上

放一段 不依赖 bundle 的内联脚本。尽早注册全局 error 监听和关键全局变量就绪检测,直接上报：

内联，才能在 “应用根本没起来” 时依然工作。

从第二层来看，主源失败回退备源 —直觉做法，还有它对 “全家桶” 的致命局限

• `onerror` 换源是 **异步插入** 新脚本。它只和 “其它动态插入的脚本” 保序，拦不住已经在 HTML 中、解析器紧接着要执行的后续脚本。

1. react 加载失败 → `onerror` 异步去备源拉 react;不过，
2. 解析器 **立刻** 执行已加载成功的 react‑dom → 此刻 `window.React`仍缺失 → 顶层抛错;
3. react‑router 、其他依赖也连锁崩溃;
4. 备源 react 稍后才就绪，但 react‑dom 已经因为缺少 global 而永远不会创建 `window.ReactDOM`。

回退备源方向对。但对互相依赖的全家桶不能靠 “每个脚本各自异步换源”，必须 受控地、按序地 做。

第三层的观点是，受控串行加载 — 真正消除竞态

串行 加载 ： react → react-dom → 路由 → 数据层。每个都按 尝试,前一个 onload 后再加载下一个,全部就绪后才启动应用。

 // 受控串行加载 : 数组顺序即依赖顺序;每个内部 自愈，全部就绪再启动
var CHAIN =;var SOURCES =;// 主源、备源
function loadOne{
if return done;// 已就绪跳过
var i = 0;{
if return done);var s=document.createElement;按理说，s.src=SOURCES + item.path;s.async=false;s.crossOrigin='anonymous';s.onload=function{ done;}，s.onerror=attempt;// 主源挂 -> 自动换备源
document.head.appendChild;})，}
{
if return startApp;// 全部准备好才启动
loadOne{
if return showFallbackUI;// 主+备都挂 -> 降级 UI
loadChain;})，});

串行 ： react-dom 的加载只会在 react 真正 onload 后才开始。从根上保证 window.React 必定先于 window.ReactDOM 存在 —— 无论单文件失败还是整段失败，都不会出现竞态。跳过已就绪全局，是为了避免重复加载导致多实例。代价是首屏稍微多一点串行开销，但换来的是 “CDN 抖一下也不整站崩”。如果你使用自动注入 CDN 的建立插件。只需要让关键依赖脱离插件自动