Nuxt 3 生产环境偶发白屏：Failed to fetch dynamically imported module 怎么排查

👁 97 次阅读

问题来源：https://github.com/nuxt/nuxt/issues/26565 这个问题的典型形态是：开发环境一切正常，自己的机器上复现不出来，但 Sentry 里持续报错，报错页面各不相同，有的首页，有的搜索页，Safari 用户偏多。日志里大部分是好的，混着一些偶发失败。这个 issue 的环境是 Windows NT、Node v21.6.1、Nuxt 3.11.1、Nitro 2.9.5，部署在 Azure App Service，作者把它定位成不确定性 bug，nuxt/nuxt#26565 最终被标记为 not planned。下面按生产可落地的顺序讲：为什么会白屏、怎么从 chunk 文件名反查组件、客户端兜底怎么写、以及部署侧最容易漏的那一环。

现象描述

浏览器控制台报 Failed to fetch dynamically imported module "/_nuxt/OpeningHours.CTqYYKGj.js"，页面直接白屏，没有错误页。几个容易忽略的特征：报错的 chunk 名每次不一样；刷新一次就好，再刷又可能出；Safari 上报得比 Chrome 多。这三条一起出现，基本可以排除业务代码里的空指针，直接往资源加载方向查。

为什么会白屏

Vite 在页面启动时注入一个预加载 helper。它读构建期生成的 import map，把源模块路径映射到带 content hash 的 chunk 文件名，然后发 <link rel="modulepreload"> 去预取。一旦某个 chunk 在 import map 里找不到对应资源，或者源站、CDN 对它返回 404、403、400，这条动态导入就抛错。关键点是这个失败发生在应用启动阶段的模块解析里，不是你的业务代码里，所以没有 try/catch 能拦住，应用直接起不来，表现就是白屏。 Nuxt 3 在 3.8 前后改过 chunk 命名策略，旧的短命名换成带 hash 的长命名。如果构建产物里有新旧命名混杂，浏览器拿旧名字去要资源就会 404。这个 issue 里作者也提到了刚升级过 Nuxt，并且看到过老命名的组件导入失败。另外 Nuxt 的 chunk 名保留了组件名，OpeningHours.CTqYYKGj.js 对应的就是 OpeningHours 这个组件。这一点是排查的关键抓手。

排查步骤

第一步，先看状态码，区分三种完全不同的根因。在 Network 面板里找标红的那个 JS 请求： 404 是资源不存在。构建产物里没有这个 chunk，或者部署把旧版本的 chunk 删掉了。 403 通常是 CDN 或源站的 ACL 拦截，或者源站把 JS 请求路由到了 HTML 入口。检查一下这个 URL 返回的 Content-Type，如果是 text/html，说明请求被网关拦下重定向了。 304 是缓存协商失败。CDN 存了一个错误的过期时间或者 ETag，导致客户端拿到的 chunk 版本跟 import map 对不上。第二步，从 chunk 名反查组件。Nuxt 的 chunk 命名保留了组件名，把 hash 前缀去掉就是源模块。到项目里搜一下：

grep -rn "OpeningHours" src/ --include="*.vue" --include="*.ts"

如果这个组件最近被改过、移动过或者拆过，重点看拆分的提交记录。拆组件经常导致 import map 里保留了旧路径而新 chunk 名已经变了。第三步，检查部署产物有没有混版本。Nuxt 输出的 .output/public/_nuxt/ 目录里，如果同时存在两个版本的 chunk，说明流水线里前一次构建的残留没清干净。Azure App Service 上多次部署如果用了增量发布，旧文件不会自动删。

ls -la .output/public/_nuxt/ | wc -l

跟预期 chunk 数量对一下，多了就是残留。第四步，看 CDN 的缓存策略。这个 issue 里作者提到 Safari 用户报得多，Safari 对 modulepreload 和 HTTP/2 预加载的行为跟 Chromium 系有差异，CDN 上如果 chunk 的 Cache-Control 配得过于保守，Safari 更容易拿到旧版本。

客户端兜底

因为白屏发生在应用启动之前，唯一的补救是把异常兜住，给用户一个可操作的提示，而不是让页面停在空白状态。

// plugins/error-handling.ts
export default defineNuxtPlugin(() => {
  const onUnhandledRejection = (event: PromiseRejectionEvent) => {
    const message = event.reason?.message || ''
    if (message.includes('Failed to fetch dynamically imported module')) {
      event.preventDefault()
      console.error('[chunk-import-fail]', message)
      window.$nuxt?.app?.$error?.(
        '资源加载失败，请刷新页面重试',
        { duration: 4000 }
      )
    }
  }
  window.addEventListener('unhandledrejection', onUnhandledRejection)
  return {
    destroy() {
      window.removeEventListener('unhandledrejection', onUnhandledRejection)
    }
  }
})

这段代码做了两件事：拦下不会让应用崩溃的 promise rejection，把它降级成一个提示条，同时上报一条自定义日志方便你在 Sentry 里统计频次。需要说明的是，$error 这个全局方法不是 Nuxt 内置的，社区里常用的实现来自 use-error-handler 之类的插件，或者你自己注入一个全局响应式对象。如果不想引依赖，直接写一行 window.location.reload() 更省事，代价是用户要手动点确认。

部署侧

这一环最容易漏。偶发白屏在 80% 的情况下不是 Nuxt 的 bug，是部署流水线或 CDN 的配置问题。一、增量部署会留旧 chunk。Azure App Service 的默认发布方式如果不清理目标目录，前一次构建的 chunk 会残留。新构建生成的 import map 已经不含旧路径，但旧 chunk 文件还在，反过来新 chunk 可能没传上去。改成全量发布，或者发布前清空 _nuxt 目录。二、CDN 上的 chunk 缓存时间要和源站一致。chunk 文件名带 hash，理论上应该长缓存，但如果 CDN 的 Cache-Control 比源站短，或者两者不匹配，就可能出现「浏览器问的是新 hash，CDN 给的是旧内容」的情况。给 _nuxt 下的 JS 文件设 immutable，其余动态路由设 no-cache。三、源站返回 HTML 的错误页会伪装成 200。有些网关在找不到资源时返回一个 HTML 404 页面并带 200 状态码，浏览器把它当 JS 解析，直接报语法错误。检查一下 chunk URL 的响应头 Content-Type，必须是 application/javascript。四、多环境并行发布。如果生产和新版本同时在跑，浏览器可能拿到新版本 import map 和旧版本 chunk。发布窗口内不要同时挂两个版本。

方案对比

方案	解决什么	适用阶段	风险
客户端 unhandledrejection 兜底	白屏变成可操作提示	立即	治标不治本，用户要手动刷新
全量发布替代增量发布	旧 chunk 残留	部署	发布耗时略增
CDN 缓存策略对齐	版本错配	部署	需重新预热缓存
检查网关错误页 Content-Type	200 伪装成 JS	排查	无
从 chunk 名反查组件源码	定位真实失败模块	排查	无
降级 builder 到 webpack	issue 作者提过的问题	排查	Nuxt 3 默认 Vite，降级有兼容成本

常见错误排查

一、报错只在生产，开发复现不出来。Vite 的开发模式用 esbuild 直接解析源文件，不走 import map 和 chunk 预加载，所以开发环境永远不会报这个错。别试图在本地复现，直接在生产日志和 Sentry 里找真实的失败 URL。二、chunk 名带 hash，以为无法对应源码。Nuxt 的 chunk 名保留了组件名，hash 只是后缀。把 _nuxt/ 下的文件名去掉 hash 部分，去 src 目录搜同名组件就能定位。三、Sentry 里看到报错，但用户截图是白屏。这两件事是同一个问题。白屏的根因就是那条动态导入失败，客户端没有兜底就会停在空白。补了兜底之后用户至少能看到提示。四、清缓存之后问题仍然偶发。说明不是缓存问题，重点看源站对不存在资源的响应。让运维用 curl 直接请求一个不存在的 chunk 路径，看返回的状态码和 Content-Type。返回 HTML 就是网关在改写。五、多环境并行发布时集中爆发。新旧版本的 import map 混在浏览器里，新 map 找不到旧 chunk。关掉并行发布窗口，让一次部署只对应一套产物。六、误以为这是 Nuxt 的框架 bug 去提 issue。#26565 被官方标成 not planned，不是因为 Nuxt 拒绝修，而是这类偶发加载失败几乎都源于部署或缓存配置。先在本地把产物和 CDN 策略对齐，再看是否还复现。

总结

Nuxt 3 生产环境出现 Failed to fetch dynamically imported module 白屏，90% 是部署产物残留或 CDN 缓存策略错配，不是框架 bug。排查顺序很固定：先看失败请求的状态码，区分 404、403、304；再用 chunk 名反查组件，确认组件有没有被拆过；然后检查 .output 目录和 CDN 缓存配置。客户端侧加一个 unhandledrejection 兜底，把白屏降级成可操作提示。这类问题官方一般不修，因为根因都在部署链路里。