前端工程化 / 系统课时

排查部署后白屏与资源 404

排查部署后白屏与资源 404

部署后白屏通常不是单一故障,而是入口页面、静态资源、前端路由、响应类型或缓存中的某一层失配。本课按浏览器请求链从外到内排查,并用构建产物、服务器配置与 HTTP 响应完成闭环验证。

学习目标

  • 根据状态码和浏览器控制台判断故障位于哪一层
  • 校准 Vite base、部署子路径与前端路由回退
  • 验证资源 MIME 类型、缓存策略和最终线上响应

先确定故障层级

先打开浏览器开发者工具的 Network 与 Console,不要一上来反复改配置。入口 HTML 返回 404,说明站点根路径或发布目录错误;HTML 为 200,但 JS、CSS 为 404,优先检查 base;深层路由刷新后 404,检查服务器回退;脚本返回 200 却被拒绝执行,检查 Content-Type 是否误为 text/html。

部署后白屏与资源 404 的逐层排查流程

排查时记录“第一个失败请求”。后续大量报错往往只是首个 JS 未加载造成的连锁结果,先修复最早出现且最接近入口的异常。

校准 base 与产物路径

应用部署在域名根路径时使用 base: '/';部署在 https://<DOMAIN>/app/ 时,应使用 /app/。Vite 构建会据此重写 HTML、CSS 和 JavaScript 中由构建系统管理的资源地址。不要把文件系统目录 /srv/www/app 当成浏览器路径写进 base。

ts
import { defineConfig } from 'vite'

export default defineConfig({
  // 浏览器实际访问前缀是 /app/,不是服务器磁盘目录
  base: '/app/',
  build: {
    outDir: 'dist',
    assetsDir: 'assets',
  },
})

该配置生效后,构建出的 dist/index.html 应引用 /app/assets/...。可以直接构建并提取资源地址:

bash
npm run build
node -e "const fs=require('node:fs');const h=fs.readFileSync('dist/index.html','utf8');console.log([...h.matchAll(/(?:src|href)=\"([^\"]+)\"/g)].map(x=>x[1]).join('\n'))"

预期输出

text
/app/assets/index-<ID>.js
/app/assets/index-<ID>.css

实际文件哈希和资源数量可能不同。若输出仍以 /assets/ 开头,说明构建没有使用目标配置或发布了旧产物;若业务代码手写了绝对路径,也需要改为导入资源、使用 import.meta.env.BASE_URL,或显式拼接部署前缀。

配置路由回退与 MIME

History 路由中的 /app/orders/42 通常不是磁盘文件。服务器应仅在应用路由没有对应文件时回退到 /app/index.html,真实缺失的 JS、CSS、图片仍应返回 404。否则脚本请求可能拿到 HTML,浏览器会以 MIME 类型不匹配拒绝执行。

下面是 Nginx 片段示例,假设 dist 内容发布到 /srv/www/app,并将配置放在 http 上下文中:

nginx
http {
  include mime.types;
  default_type application/octet-stream;

  server {
    listen 80;
    server_name _;
    root /srv/www;

    location /app/assets/ {
      try_files $uri =404;
      add_header Cache-Control "public, max-age=31536000, immutable";
    }

    location = /app/index.html {
      add_header Cache-Control "no-cache";
    }

    location /app/ {
      try_files $uri $uri/ /app/index.html;
    }
  }
}

保存后先校验语法:

bash
nginx -t

预期输出

text
nginx: configuration file <PATH> syntax is ok
nginx: configuration file <PATH> test is successful

配置文件路径会随系统安装方式变化。若使用 Apache、Caddy、对象存储或 CDN,应实现相同原则:应用路由回退到入口,静态资源按真实文件返回,并为 .js、.css 等提供正确响应类型。

清理缓存并逐层验证

发布新版本时先上传带哈希的资源,再更新 index.html。资源文件可长期缓存,入口 HTML 不宜长期强缓存,否则旧入口仍会引用已删除的旧哈希文件。使用 Service Worker 的应用还要检查其更新策略,并在测试时确认旧缓存已退出控制。

上线后用实际域名验证三个关键请求:

bash
curl -I https://<DOMAIN>/app/
curl -I https://<DOMAIN>/app/assets/index-<ID>.js
curl -I https://<DOMAIN>/app/orders/42

预期输出

text
HTTP/2 200
content-type: text/html

HTTP/2 200
content-type: text/javascript

HTTP/2 200
content-type: text/html

不同服务器可能返回 application/javascript,这同样正常。若第二个请求返回 text/html,说明静态资源被错误回退到入口;若第三个请求为 404,说明 History 路由回退尚未生效。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查部署后白屏与资源 404

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通