前端工程化 / 系统课时
排查部署后白屏与资源 404
排查部署后白屏与资源 404
部署后白屏通常不是单一故障,而是入口页面、静态资源、前端路由、响应类型或缓存中的某一层失配。本课按浏览器请求链从外到内排查,并用构建产物、服务器配置与 HTTP 响应完成闭环验证。
学习目标
- 根据状态码和浏览器控制台判断故障位于哪一层
- 校准 Vite
base、部署子路径与前端路由回退 - 验证资源 MIME 类型、缓存策略和最终线上响应
先确定故障层级
先打开浏览器开发者工具的 Network 与 Console,不要一上来反复改配置。入口 HTML 返回 404,说明站点根路径或发布目录错误;HTML 为 200,但 JS、CSS 为 404,优先检查 base;深层路由刷新后 404,检查服务器回退;脚本返回 200 却被拒绝执行,检查 Content-Type 是否误为 text/html。

排查时记录“第一个失败请求”。后续大量报错往往只是首个 JS 未加载造成的连锁结果,先修复最早出现且最接近入口的异常。
校准 base 与产物路径
应用部署在域名根路径时使用 base: '/';部署在 https://<DOMAIN>/app/ 时,应使用 /app/。Vite 构建会据此重写 HTML、CSS 和 JavaScript 中由构建系统管理的资源地址。不要把文件系统目录 /srv/www/app 当成浏览器路径写进 base。
import { defineConfig } from 'vite'
export default defineConfig({
// 浏览器实际访问前缀是 /app/,不是服务器磁盘目录
base: '/app/',
build: {
outDir: 'dist',
assetsDir: 'assets',
},
})该配置生效后,构建出的 dist/index.html 应引用 /app/assets/...。可以直接构建并提取资源地址:
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'))"预期输出
/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 上下文中:
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;
}
}
}保存后先校验语法:
nginx -t预期输出
nginx: configuration file <PATH> syntax is ok
nginx: configuration file <PATH> test is successful配置文件路径会随系统安装方式变化。若使用 Apache、Caddy、对象存储或 CDN,应实现相同原则:应用路由回退到入口,静态资源按真实文件返回,并为 .js、.css 等提供正确响应类型。
清理缓存并逐层验证
发布新版本时先上传带哈希的资源,再更新 index.html。资源文件可长期缓存,入口 HTML 不宜长期强缓存,否则旧入口仍会引用已删除的旧哈希文件。使用 Service Worker 的应用还要检查其更新策略,并在测试时确认旧缓存已退出控制。
上线后用实际域名验证三个关键请求:
curl -I https://<DOMAIN>/app/
curl -I https://<DOMAIN>/app/assets/index-<ID>.js
curl -I https://<DOMAIN>/app/orders/42预期输出
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 路由回退尚未生效。