Vue / 系统课时
排查生产环境故障
排查生产环境故障
生产环境故障最怕同时猜多个原因。本课建立一套从“能否访问”到“配置是否生效”的固定排查顺序,帮助你快速区分静态资源、路由回退、跨域、缓存和环境变量问题,并用可重复的验证结果闭环。
学习目标
- 按固定顺序定位生产环境故障,避免无效试错
- 识别资源加载、路由刷新、跨域、缓存与环境配置的典型现象
- 使用浏览器和命令行完成修复后的回归验证
先固定排查顺序
先确认故障范围:是所有用户都失败,还是仅个别浏览器、网络或账号失败;是首页打不开,还是进入页面后接口报错。随后按“入口页面 → 静态资源 → 前端路由 → API 请求 → 缓存 → 环境配置”的顺序检查。前一步未通过时,不要急着修改后面的配置。

用请求结果缩小范围
先用 curl 绕过页面交互,直接验证入口、静态资源、路由回退和跨域响应。下面的域名与哈希是示例,运行前应替换为实际值。
curl -I https://admin.example.com/
curl -I https://admin.example.com/assets/index-<ID>.js
curl -I https://admin.example.com/system/users
curl -i -X OPTIONS https://api.example.com/users \
-H "Origin: https://admin.example.com" \
-H "Access-Control-Request-Method: GET"预期输出
HTTP/2 200
content-type: text/html
HTTP/2 200
content-type: application/javascript
HTTP/2 200
content-type: text/html
HTTP/2 204
access-control-allow-origin: https://admin.example.com
access-control-allow-methods: GET预检请求也可能返回 200,关键是响应中包含正确的跨域允许头。首页不是 200,优先检查域名、证书、反向代理和部署目录。静态资源返回 404,通常是构建产物未完整上传、base 路径错误或 HTML 引用了不存在的旧哈希文件。
业务路由刷新后应返回 index.html;若直接返回 404,说明服务器没有配置单页应用回退。预检请求缺少允许来源响应头,则应在 API 网关或后端修复跨域,而不是在前端绕过安全限制。
修复路由刷新与资源路径
Vue Router 使用 history 模式时,浏览器刷新 /system/users 会直接向服务器请求该路径。服务器必须在文件不存在时回退到 index.html。Nginx 可使用以下配置片段:
location / {
try_files $uri $uri/ /index.html;
}
location /api/ {
proxy_pass https://api.example.com/;
}重新加载 Nginx 后,再执行上一节对业务路由的 curl -I。返回 200 且 content-type 为 text/html,说明路由回退已经生效。若应用部署在 /admin/ 子路径,还要同步检查 Vite 的 base、路由基路径和服务器目录,三者必须一致。
区分跨域、接口错误与环境变量
浏览器控制台出现 CORS 提示时,先查看 Network 中的真实请求地址。请求仍指向测试域名,说明构建阶段读取了错误环境文件;请求地址正确但预检失败,才是服务端跨域配置问题。生产环境变量示例:
VITE_API_BASE_URL=https://api.example.com
VITE_APP_ENV=productionVite 会在构建阶段把 VITE_ 变量写入产物,部署后修改服务器上的 .env 不会自动改变已经生成的 JavaScript。修复后必须重新构建,并在产物中搜索旧域名;若仍能找到,说明配置没有被正确替换。
接口返回 401、403 或 500 时,也不要误判为跨域。只要浏览器能够读取响应状态和响应体,请求就已经通过跨域检查,应继续排查令牌、权限、网关转发或后端异常。
处理缓存与版本不一致
当部分用户正常、部分用户白屏,或 HTML 引用了已删除的旧资源时,优先怀疑缓存。先在浏览器禁用缓存并强制刷新,再检查 CDN、反向代理和 Service Worker。推荐让 index.html 短缓存或不缓存,让带内容哈希的 JS、CSS 长缓存。
| 现象 | 优先检查 | 判断依据 |
|---|---|---|
| 首页正常,资源 404 | 构建产物与 base |
HTML 中的资源路径与服务器目录不一致 |
| 路由跳转正常,刷新 404 | history 回退 | 业务路径未返回 index.html |
| 控制台出现 CORS | API 响应头 | 预检请求没有允许来源或方法 |
| 仅部分用户白屏 | CDN、浏览器、Service Worker | 强制刷新后恢复或命中旧哈希文件 |
| 请求发往测试地址 | 构建环境变量 | 产物中仍包含旧 API 域名 |
不要用“清空所有 CDN 缓存”作为第一步。更稳妥的做法是先确认旧 HTML 或旧 Service Worker 是否仍在分发,再执行精确失效,避免扩大影响。
完成修复后的回归验证
修复后至少验证四条路径:首次打开首页、直接刷新深层路由、登录后调用 API、发布新版本后刷新旧标签页。浏览器 Network 中不应出现静态资源 404,API 不应出现 CORS 阻断,控制台不应有未捕获异常。
同时记录故障时间、影响范围、根因、修改项和验证证据。只写“已恢复”无法支撑后续复盘;至少保留响应状态、关键请求地址、部署版本和缓存处理结果。