Vue / 系统课时

排查生产环境故障

排查生产环境故障

生产环境故障最怕同时猜多个原因。本课建立一套从“能否访问”到“配置是否生效”的固定排查顺序,帮助你快速区分静态资源、路由回退、跨域、缓存和环境变量问题,并用可重复的验证结果闭环。

学习目标

  • 按固定顺序定位生产环境故障,避免无效试错
  • 识别资源加载、路由刷新、跨域、缓存与环境配置的典型现象
  • 使用浏览器和命令行完成修复后的回归验证

先固定排查顺序

先确认故障范围:是所有用户都失败,还是仅个别浏览器、网络或账号失败;是首页打不开,还是进入页面后接口报错。随后按“入口页面 → 静态资源 → 前端路由 → API 请求 → 缓存 → 环境配置”的顺序检查。前一步未通过时,不要急着修改后面的配置。

Vue 3 管理后台生产故障排查流程

用请求结果缩小范围

先用 curl 绕过页面交互,直接验证入口、静态资源、路由回退和跨域响应。下面的域名与哈希是示例,运行前应替换为实际值。

bash
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"

预期输出

text
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 可使用以下配置片段:

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 中的真实请求地址。请求仍指向测试域名,说明构建阶段读取了错误环境文件;请求地址正确但预检失败,才是服务端跨域配置问题。生产环境变量示例:

dotenv
VITE_API_BASE_URL=https://api.example.com
VITE_APP_ENV=production

Vite 会在构建阶段把 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 阻断,控制台不应有未捕获异常。

同时记录故障时间、影响范围、根因、修改项和验证证据。只写“已恢复”无法支撑后续复盘;至少保留响应状态、关键请求地址、部署版本和缓存处理结果。

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

目录与阅读设置

阅读设置

17

记录一个想法

排查生产环境故障

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

登录哪都通