构建通过,说明工具按当前配置生成了产物。用户打开页面后,浏览器还要解析脚本,再执行页面代码。遇到不支持的语法,脚本会在解析时报错。直接调用缺失的方法,会在执行到那一行时抛出异常。两种错误都可能中断首屏渲染,让用户看到白屏。
两起独立的线上异常都发生在执行阶段。一起出在组件查找数组元素时,另一起出在客户端生成标识时。
数组方法缺失导致页面白屏
一份线上记录显示,页面在旧版浏览器里白屏。下面的 items 代指报错中的实际调用对象。
TypeError: items.findLast is not a function
浏览器内核缺少 findLast,页面在调用前也没有加载兼容实现。
到兼容表里查一个具体功能
ECMAScript 规范定义语法和内置 API 应有的行为。V8、SpiderMonkey 和 JavaScriptCore 等引擎各自实现这些能力,再随浏览器版本发布。因此,同一项功能在不同浏览器中的支持时间可能不同,早期实现的行为也可能有差异。
可以直接搜索功能名,例如 optional chaining 或 Array.prototype.findLast。下表列出这两项功能在三个桌面浏览器中的首个支持版本。Can I Use 官网
| 功能 | Chrome | Firefox | Safari |
|---|---|---|---|
可选链语法 ?. | 80 | 74 | 13.1 |
数组方法 findLast | 97 | 104 | 15.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,可以用同样的检测思路选择可用的随机源。
分别验证各条路径后,再用同一份发布产物在目标环境从打开页面走到实际操作,确认首屏能渲染、功能能完成,需要降级时也能得到预期结果。
参考与数据源
- Can I Use 可选链支持表
- Can I Use findLast 支持表
- MDN Polyfill 术语说明
- ECMAScript Array.prototype.findLast
- ECMAScript Array.prototype.findLastIndex
- core-js Array 定向入口
- core-js 全局与局部用法
- Next.js 浏览器支持与 polyfill
- Next.js 客户端启动入口
- React createRoot
- Vue 浏览器支持
- Vite 生产构建与浏览器兼容
- Babel preset-env
- Babel 可选链转译
- TypeScript lib 配置
- W3C Web Crypto 接口
- W3C 安全上下文与可信来源
- uuid 浏览器支持与随机数来源
- Node.js 包条件导出