构建通过了,为什么有些浏览器还会白屏?

0 阅读9分钟

构建通过,说明工具按当前配置生成了产物。用户打开页面后,浏览器还要解析脚本,再执行页面代码。遇到不支持的语法,脚本会在解析时报错。直接调用缺失的方法,会在执行到那一行时抛出异常。两种错误都可能中断首屏渲染,让用户看到白屏。

两起独立的线上异常都发生在执行阶段。一起出在组件查找数组元素时,另一起出在客户端生成标识时。

数组方法缺失导致页面白屏

一份线上记录显示,页面在旧版浏览器里白屏。下面的 items 代指报错中的实际调用对象。

TypeError: items.findLast is not a function

浏览器内核缺少 findLast,页面在调用前也没有加载兼容实现。

到兼容表里查一个具体功能

ECMAScript 规范定义语法和内置 API 应有的行为。V8、SpiderMonkey 和 JavaScriptCore 等引擎各自实现这些能力,再随浏览器版本发布。因此,同一项功能在不同浏览器中的支持时间可能不同,早期实现的行为也可能有差异。

可以直接搜索功能名,例如 optional chaining 或 Array.prototype.findLast。下表列出这两项功能在三个桌面浏览器中的首个支持版本。Can I Use 官网

功能ChromeFirefoxSafari
可选链语法 ?.807413.1
数组方法 findLast9710415.4

假设产品要支持 Chrome 90,?. 可以交给浏览器解析,findLast 则需要兼容实现。

移动端浏览器和内嵌 WebView 要按各自的内核与版本核对,兼容表里的部分支持备注也值得查看。

用 polyfill 补齐数组方法

为缺失或实现不完整的 API 提供兼容实现的代码叫 polyfill。补齐数组方法后,组件可以继续调用 items.findLast(...)。同样的办法也可用于 Promise.allSettled、URLSearchParams 等接口,前提是环境提供了实现所需的基础能力。

下面同时演示返回匹配值的 findLast 和返回下标的 findLastIndex。将代码保存为 repro.cjs,在安装了 core-js 的目录执行 node repro.cjs,用独立进程模拟这两个方法缺失。

delete Array.prototype.findLast
delete Array.prototype.findLastIndex

try {
  [1, 9, 4].findLast(value => value > 1)
} catch (error) {
  console.log(error.name) // TypeError
}

require('core-js/actual/array/find-last')
require('core-js/actual/array/find-last-index')

console.log([1, 9, 4].findLast(value => value > 1)) // 4
console.log([1, 9, 4].findLastIndex(value => value > 1)) // 2

第一次调用抛出 TypeError。加载补丁后,匹配到的值是 4,它在数组中的下标是 2。

手写补丁在普通数组上通过,换个对象就出错

既然倒序循环就能找到最后一个匹配项,自己补一个方法行不行?下面让手写版和原生版处理同一组输入。手写版先用 >>> 0 处理长度,示例只保留查找过程,可在支持 findLastIndex 的 Node.js 中单独运行。

function findLastIndexFallback(predicate, thisArg) {
  const length = this.length >>> 0
  for (let index = length - 1; index >= 0; index--) {
    if (predicate.call(thisArg, this[index], index, this)) return index
  }
  return -1
}

const nativeFindLastIndex = Array.prototype.findLastIndex
const items = [1, 9, 4]
const greaterThanOne = value => value > 1

console.log(findLastIndexFallback.call(items, greaterThanOne)) // 2
console.log(nativeFindLastIndex.call(items, greaterThanOne)) // 2

const length = 2 ** 32
const arrayLike = { length, [length - 1]: 'last' }
const matches = value => value === 'last'

console.log(findLastIndexFallback.call(arrayLike, matches)) // -1
console.log(nativeFindLastIndex.call(arrayLike, matches)) // 4294967295

普通数组上的两次调用都输出 2,只测这组输入很难发现问题。类数组对象只有 length 和最后一个下标对应的属性,无需创建几十亿个元素。findLastIndex 支持通过 .call() 在这个对象上运行,原生方法第一次就找到 'last'。手写版的 >>> 0 把 2 ** 32 转成了无符号 32 位整数 0,循环一次也没执行。

如果用这段手写实现做补丁,调用方会把 -1 当成没找到匹配项。这类错误有合法的返回值,比抛异常更难察觉。移除原生方法后用 core-js 补齐,同一个输入仍能返回 4294967295。

把手写函数作为标准方法提供,就要覆盖该方法接受的各种输入和边界行为。这类补齐工作优先交给有规范和测试支撑的成熟 polyfill。业务只需要处理某种已知输入时,可以把实现留在调用点,用业务函数名表达它支持的范围。

在组件首次调用前加载 polyfill

如果首屏组件就会调用 findLast,可以在客户端启动入口定向导入所需的模块。

import 'core-js/actual/array/find-last'
import 'core-js/actual/array/find-last-index'

React 单页应用可以在调用 createRoot 前加载,Vue 单页应用可以在调用 createApp(...).mount(...) 前加载。Next.js App Router 可用 instrumentation-client.ts,Pages Router 可在自定义 _app 顶层导入。框架自带的补丁覆盖哪些 API,可以按安装版本核对。

加载方式适用条件
入口定向导入只缺少少量 API,或首屏组件已经依赖这些方法
由构建工具注入已有一组明确的目标浏览器。Vite 可用 @vitejs/plugin-legacy 生成兼容产物。Babel 7 可用 preset-env 的 useBuiltIns,Babel 8 可用 babel-plugin-polyfill-corejs3
检测后动态加载只有可选功能会用到该方法。先检测,再等待补丁加载完毕,最后启动功能

即使旧内核能加载 ES 模块,也要核对构建插件是否覆盖了第三方组件调用的 API。主页面的原型补丁只作用于自己的执行上下文,iframe 和 Worker 要分别检查。

组件库也可以用 core-js-pure 等局部实现兼容自己控制的调用点。已发布的第三方组件继续调用原型方法时,应用需要在它运行前提供该方法。

回到页面验证组件能否渲染

在新版 Chromium 中模拟方法缺失并加载这两个补丁后,受影响的组件恢复了渲染。实际旧内核仍需单独验证。

初始化失败时,检查随机数接口

数组查找可以用已有的 JavaScript 能力实现。生成 UUID v4 还需要可信的随机字节。另一起线上异常发生在客户端初始化时,代码调用 crypto.randomUUID() 生成标识,随即抛出异常。

TypeError: crypto.randomUUID is not a function

记录只确认该方法当时不可调用,具体原因仍待确认。排查时可以先核对代码访问的是浏览器的 globalThis.crypto、Node.js 的 node:crypto,还是打包器选中的浏览器替代模块,再检查该环境的 isSecureContext 和方法可用性。

检查环境还能提供什么随机源

浏览器只在安全上下文中提供 randomUUID()。如果环境实现了 getRandomValues(),普通 HTTP 页面也能用它取随机字节。测试 HTTP 场景时,应区分普通 HTTP 站点和通常被视作可信来源的 localhost。

按标识的用途决定怎么降级

可以把随机源检测放进生成函数。函数优先调用原生方法,也可以把 getRandomValues() 提供的随机字节交给 uuid 库。返回 undefined 时,调用方再决定这项操作能否继续。

import { v4 as uuidv4 } from 'uuid'

export function createUuid(): string | undefined {
  const crypto = globalThis.crypto
  if (typeof crypto?.randomUUID === 'function') return crypto.randomUUID()
  if (typeof crypto?.getRandomValues === 'function') {
    return uuidv4({ random: crypto.getRandomValues(new Uint8Array(16)) })
  }
}
本地模拟条件验证结果
原生 randomUUID() 可用使用原生 UUID
只有 getRandomValues()用随机字节生成 UUID v4
两种方法都缺失本地日志使用临时标识,服务端要求标准 UUID 的操作停止并提示原因

本地回归也验证了同一次操作在重试时沿用原请求标识。令牌、密钥和挑战值各有自己的安全随机源要求。

跨端库如何提供随机能力

同一个库可能运行在浏览器和 Node.js 中。库作者可以用条件导出把 Node.js 专用依赖放在对应入口,在调用时检测可用的随机源,也可以接受调用方提供的随机源。把随机源的要求和失败结果写进接口约定,接入方就能在使用前判断这条路径是否适用。

怎么判断该转译、补齐还是降级

先用报错定位失败的语法或 API,再核对浏览器或 WebView 的版本、实际收到的脚本和代码执行的位置。TypeScript 的 lib 提供的是类型检查用的声明,API 是否可用要到运行环境里确认。

方式怎么判断怎么处理怎么验证
语法转译目标浏览器无法解析发布脚本中的语法,例如 ?.设置构建目标,让工具生成目标浏览器能解析的代码在目标浏览器加载实际构建产物,确认脚本能解析并完成初始化
polyfill脚本能执行,缺失或实现不完整的 API 可以用已有能力等价实现,例如 findLast选用有测试覆盖的 polyfill,在首次调用前加载到对应的执行上下文检查发布产物是否包含补丁,再模拟原生方法缺失,确认首次调用成功、结果正确
能力检测与降级功能依赖环境提供的能力,例如生成 UUID 所需的可信随机源运行时检查能力。替代路径满足原要求时继续,条件不足时按用途降级或提示分别测试原生能力可用、仅替代能力可用、两者都不可用,核对每条路径的结果和提示

三种方式可以组合。例如同一个页面要支持 Chrome 79,构建时需要转译 ?.,运行时还可以先检测 findLast,缺失就加载 polyfill。页面如果还要生成 UUID,可以用同样的检测思路选择可用的随机源。

分别验证各条路径后,再用同一份发布产物在目标环境从打开页面走到实际操作,确认首屏能渲染、功能能完成,需要降级时也能得到预期结果。

参考与数据源