旧内核白屏:CSS 目标与缺失 API 兜底

2026-11-19 前端开发 有希 42 次浏览

旧内核打开页面先闪一下再白屏,通常是客户端接管时缺 API 抛错;手机看到桌面布局,则是媒体查询被整条丢弃。两者根因不同,要分开修。

先分清三种“白屏”

同样叫白屏,发生时机不一样,处理方向也完全不同。先看控制台和页面状态,再决定改哪一层。

现象出错时机常见根因控制台特征
内容一闪后整页变白客户端接管渲染时缺 Object.hasOwn 等运行时 APITypeError: 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 }]
    }
  }
})

这里有三个约束,少一个都可能失效:

  1. 必须是内联脚本。外链或模块脚本要等下载、解析、执行,而 Vue 的接管可能已经开始。内联的经典脚本会随 HTML 一起到达并立即执行,顺序天然在前。
  2. 必须是 ES5 语法。这段脚本自己的任务就是“让旧内核能跑”,如果里面出现箭头函数、模板字符串或可选链,解析阶段就会失败,兜底等于没写。
  3. 只在缺失时定义。if (!o[n]) 保证新浏览器继续用原生实现,不会被降级实现覆盖;Object.defineProperty 设成不可枚举,避免这些方法出现在 for...in 里。

覆盖范围也要明确:它只补了门户实际用到的六个 API,不是 core-js 的替代品。遇到新的缺失 API,先看控制台报错,再按同样方式补一个最小实现,不要一次性塞整套 polyfill。

下表是这些 API 的原生支持起点,可以和目标内核对照:

APIChromium 原生支持
String.prototype.replaceAll85
Array.prototype.at / String.prototype.at92
crypto.randomUUID92(且要求安全上下文)
Object.hasOwn93
Array.prototype.findLast / findLastIndex97

目标内核只要低于对应版本,就会在第一次调用时出错。

第三层:构建目标管语法,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 处理。改完后别只看新浏览器,拿一台真实旧设备走一遍点击和断点,才算验证完成。更多前端排错文章见 前端开发。

评论

登录后即可参与评论

还没有评论,来说两句吧

相关文章