旧内核白屏:CSS 目标与缺失 API 兜底
旧内核打开页面先闪一下再白屏,通常是客户端接管时缺 API 抛错;手机看到桌面布局,则是媒体查询被整条丢弃。两者根因不同,要分开修。
先分清三种“白屏”
同样叫白屏,发生时机不一样,处理方向也完全不同。先看控制台和页面状态,再决定改哪一层。
| 现象 | 出错时机 | 常见根因 | 控制台特征 |
|---|---|---|---|
| 内容一闪后整页变白 | 客户端接管渲染时 | 缺 Object.hasOwn 等运行时 API | TypeError: Object.hasOwn is not a function |
| 首屏内容一直在,但永远点不动 | 脚本解析阶段 | 产物里有旧内核不认识的语法 | SyntaxError,整包不执行 |
| 能看能点,布局退回桌面版 | CSS 解析阶段 | 媒体查询写法太新,整条被丢弃 | 无报错,断点就是不生效 |
第一种最容易被误判成“接口慢”或“SSR 失败”。实际上 HTML 早已到达,失败发生在浏览器接管页面的那一步;首屏被清空只是后果。第二种更隐蔽:页面看起来有内容,其实是服务端渲染的静态壳,所有点击和路由都没挂上。
第一层:闪一下后白屏,是 API 缺失
Nuxt 的首屏流程是:服务端先输出完整 HTML,浏览器显示;随后客户端脚本加载,Vue 接管这份 DOM 并绑定事件。Vue 3.5 的运行时在接管阶段会直接调用 Object.hasOwn,例如 runtime-core.esm-bundler.js 里的 hasOwn(rawSetupState, key)、hasOwn(props, key)。如果这个 API 不存在,第一次调用就抛错,整个挂载过程中断。
可以用 Node 模拟缺失环境,把几个新 API 删掉再跑兜底脚本,观察前后差异:
// 先删掉原生实现,模拟旧内核
delete Object.hasOwn
delete Array.prototype.at
delete String.prototype.at
delete String.prototype.replaceAll
delete Array.prototype.findLast
delete Array.prototype.findLastIndex
console.log('before', typeof Object.hasOwn, typeof [].at, typeof ''.replaceAll)
// before undefined undefined undefined
// 执行门户里的内联兜底脚本(见下一节)
// ...
console.log('after', typeof Object.hasOwn, typeof [].at, typeof ''.replaceAll)
// after function function function
console.log([1, 2, 3].at(-1), 'a-b'.replaceAll('-', '+'), [1, 2, 3, 4].findLast(n => n % 2 === 0))
// 3 a+b 4
这段输出就是判断“是不是 API 缺失”的最快方式:如果 typeof Object.hasOwn 是 undefined,白屏基本可以定案。至于首屏为何会闪,可参考 Nuxt 首屏不一致排查 里对服务端输出与客户端接管差异的分析。
第二层:兜底脚本必须内联,而且只能是 ES5
门户的兜底脚本没有放进 npm 包,也没有走模块导入,而是直接写在 app.head.script 里:
// nuxt.config.ts
const LEGACY_API_POLYFILL = `(function(){
var d=function(o,n,f){
if(!o[n])Object.defineProperty(o,n,{value:f,writable:true,configurable:true})
};
d(Object,"hasOwn",function(o,k){return Object.prototype.hasOwnProperty.call(o,k)});
d(Array.prototype,"at",function(n){
n=Math.trunc(n)||0;
if(n<0)n+=this.length;
return n<0||n>=this.length?void 0:this[n]
});
d(String.prototype,"at",function(n){
n=Math.trunc(n)||0;
if(n<0)n+=this.length;
return n<0||n>=this.length?void 0:this.charAt(n)
});
d(String.prototype,"replaceAll",function(p,r){
return p instanceof RegExp?this.replace(p,r):this.split(p).join(r)
});
d(Array.prototype,"findLast",function(f,t){
for(var i=this.length-1;i>=0;i--)if(f.call(t,this[i],i,this))return this[i]
});
d(Array.prototype,"findLastIndex",function(f,t){
for(var i=this.length-1;i>=0;i--)if(f.call(t,this[i],i,this))return i;
return -1
})
})();`
export default defineNuxtConfig({
app: {
head: {
script: [{ innerHTML: LEGACY_API_POLYFILL }]
}
}
})
这里有三个约束,少一个都可能失效:
- 必须是内联脚本。外链或模块脚本要等下载、解析、执行,而 Vue 的接管可能已经开始。内联的经典脚本会随 HTML 一起到达并立即执行,顺序天然在前。
- 必须是 ES5 语法。这段脚本自己的任务就是“让旧内核能跑”,如果里面出现箭头函数、模板字符串或可选链,解析阶段就会失败,兜底等于没写。
- 只在缺失时定义。
if (!o[n])保证新浏览器继续用原生实现,不会被降级实现覆盖;Object.defineProperty设成不可枚举,避免这些方法出现在for...in里。
覆盖范围也要明确:它只补了门户实际用到的六个 API,不是 core-js 的替代品。遇到新的缺失 API,先看控制台报错,再按同样方式补一个最小实现,不要一次性塞整套 polyfill。
下表是这些 API 的原生支持起点,可以和目标内核对照:
| API | Chromium 原生支持 |
|---|---|
String.prototype.replaceAll | 85 |
Array.prototype.at / String.prototype.at | 92 |
crypto.randomUUID | 92(且要求安全上下文) |
Object.hasOwn | 93 |
Array.prototype.findLast / findLastIndex | 97 |
目标内核只要低于对应版本,就会在第一次调用时出错。
第三层:构建目标管语法,CSS 目标管断点
把 polyfill 补上后,白屏可能变成“首屏一直在但不可交互”,原因在打包产物本身。Vite 的 build.target 决定 JavaScript 降到什么语法,cssTarget 决定 CSS 降到什么写法,两者默认值不同,必须一起改。
export default defineNuxtConfig({
vite: {
build: {
target: ['chrome87', 'safari14', 'firefox78'],
cssTarget: ['chrome87', 'safari14', 'firefox78']
}
}
})
语法层:build.target
用项目里的 esbuild 0.25.12 对同一段代码分别按两个目标压缩,输出差异很直接:
class A { #x = 1; static { this.y = 2 } has(o) { return #x in o } }
# --target=chrome111
class A{#s=1;static{this.y=2}has(s){return#s in s}}
# --target=chrome87
var c=t=>{throw TypeError(t)};var h=(t,s)=>Object(s)!==s?c('Cannot use the "in" operator on this value'):t.has(s);var n=(t,s,r)=>s.has(t)?c("Cannot add the same private member more than once"):s instanceof WeakSet?s.add(t):s.set(t,r);var a;const i=class i{constructor(){n(this,a,1)}has(s){return h(a,s)}};a=new WeakMap,i.y=2;let A=i;
chrome111 保留了私有字段、静态块和私有品牌检查;chrome87 则把它们降级成 WeakMap 和辅助函数。旧内核在解析阶段遇到 static{ 或 #x in 会直接报语法错误,整个包不执行,页面就只剩服务端渲染的静态内容。
样式层:cssTarget
CSS 的问题更隐蔽。Vite 8 默认按 chrome111 用 lightningcss 压缩样式,会把传统的 max-width 改写成 Media Queries Level 4 的区间语法。用 lightningcss 1.33.0 实测:
# targets: { chrome: 111 << 16 }, minify: true
@media (width<=767px){.nav{display:none}}
# targets: { chrome: 87 << 16 }, minify: true
@media (max-width:767px){.nav{display:none}}
width<= 这种写法要到 Chromium 104 才支持。更低的内核解析不了这条 at-rule,会把整个媒体查询块丢掉,于是手机上的断点全部失效:导航被挤成竖排、页面横向溢出且无法滑动,看起来就是“桌面版塞进了手机屏幕”。这类问题控制台没有任何报错,只能靠对比构建产物确认。
运行时还有一处:crypto.randomUUID
除了 Vue 运行时,业务代码也会踩 API 版本。访问统计插件要生成访客和会话 ID,crypto.randomUUID 需要 Chromium 92+,而且只在 HTTPS 或 localhost 等安全上下文可用。直接调用会在 ensureId 里抛错,打断统计上报和路由回调。
门户把生成逻辑收进了一个带兜底的函数:
export function generateUuidV4(): string {
if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
return crypto.randomUUID()
}
const bytes = randomBytes(16)
bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40
bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80
const hex = [...bytes].map(b => b.toString(16).padStart(2, '0')).join('')
return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
}
bytes[6] 和 bytes[8] 的两行位运算是 UUID v4 的版本位和变体位,保证兜底结果同样符合规范;随机源优先 crypto.getRandomValues,非安全上下文再退回 Math.random。这段实现来自提交 9109656,同一提交还补了内联 polyfill 和构建目标。
怎么验证
先确认内核版本,再按三层分别检查。UA 里能读出的内核信息有限,可以用 UA 解析工具 拆开看,但最终判断仍以特性检测为准。
# 1. 确认 SSR 输出里有内容(有内容说明不是服务端渲染失败)
curl -s https://example.com/ -o page.html
grep -o '<h1[^>]*>' page.html | head -1
# 2. 确认兜底脚本被内联到 head
grep -o 'Object.hasOwn' page.html | head -1
# 3. 确认构建产物没有 Media Queries L4 区间语法
grep -o '@media (width<=' .output/public/_nuxt/*.css | wc -l
# 4. 确认 JS 没保留旧内核不认识的语法
grep -o 'static{' .output/public/_nuxt/*.js | wc -l
| 验证项 | 期望结果 | 实测结果 |
|---|---|---|
| 缺失 API 前后 | 前为 undefined,后为 function | 六个 API 全部从 undefined 变为 function |
| 兜底后调用 | at(-1)、replaceAll、findLast 正常 | 3、a+b、4 |
| esbuild chrome111 | 保留 static{、#x in | 原样保留 |
| esbuild chrome87 | 降级为 WeakMap 辅助代码 | 已降级 |
| lightningcss chrome111 | 输出 @media (width<=767px) | 与预期一致 |
| lightningcss chrome87 | 输出 @media (max-width:767px) | 与预期一致 |
在旧内核真机上再补两项人工检查:首屏出现后是否还能点击;手机宽度下导航是否保持横向并可滑动。两项都通过,才算三层都修完。
边界与坑
- 不覆盖 IE。目标下限是 chrome87 / safari14 / firefox78,IE 缺的不只是几个 API,不在同一套方案里。
- polyfill 不是越多越好。补得越多,内联脚本越大,而且可能覆盖掉原生实现的优化。只补控制台真正报错的 API。
- 不要用 UA 判断代替特性检测。国产浏览器的 UA 经常伪装或省略版本号,同一版本号也可能对应不同内核。判断能力用
typeof,判断版本只作参考。 - 降目标会让所有浏览器都跑降级代码。新浏览器不会因此变慢到可感知,但包体会略增;是否值得,取决于你的真实用户分布。
- CSS 目标默认值随工具版本变化。升级 Vite 或 lightningcss 后要重新检查产物,别假设配置一直生效。
- 验证前先清缓存。CDN 或 Service Worker 可能还在发旧哈希的 CSS,看起来像“改了没用”;确认页面引用的是新文件名。
FAQ
为什么内容先出现再白屏?
因为服务端渲染的 HTML 先到达并显示,客户端脚本随后接管。接管时缺 API 抛错,页面被清空。HTML 本身没问题,问题在第二步。
只降 build.target 不降 cssTarget 行不行?
不行。两个配置控制不同产物:前者管 JavaScript 语法,后者管 CSS 写法。只降 JS,媒体查询仍可能输出 width<=,手机布局照样失效。
有 polyfill 还需要降语法目标吗?
需要。polyfill 解决“运行时缺函数”,降目标解决“解析器不认识语法”。语法错误发生在脚本执行之前,polyfill 再全也来不及运行。
降目标会影响新浏览器性能吗?
影响很小。多出来的通常是少量辅助函数和更保守的语法,现代浏览器执行这些代码没有明显差异。真正需要关注的是包体大小和缓存策略。
怎么确认是 CSS 断点问题?
看现象:页面能交互、控制台无报错,但手机宽度下仍是桌面布局。再查构建后的 CSS 是否含 @media (width<=,有就说明断点被改写成旧内核不支持的语法。
小结
旧内核白屏不是一个问题,而是三层:挂载时缺 API、脚本里有新语法、媒体查询被丢弃。先看控制台和页面状态定位到层,再分别用内联 ES5 兜底、build.target 和 cssTarget 处理。改完后别只看新浏览器,拿一台真实旧设备走一遍点击和断点,才算验证完成。更多前端排错文章见 前端开发。
Comments
No comments yet — be the first to say something