开发排障笔记

深浅主题

路由刷新 404 ​

问题现象 ​

站内点击可以进入详情页，但直接访问或刷新同一 URL 返回服务器 404。还需区分 API 404 与 HTML 路由 404。

适用环境 ​

Vue Router 4 HTML5 history；Caddy 2 静态托管。

本文是可复用的排障示例，不代表某次个人生产事故。命令中的名称、账号和数据均为示例，执行前请替换为已确认的目标。

复现或诊断步骤 ​

  1. 使用 curl -I 检查直达路由的状态及 Content-Type。
  2. 确认使用 createWebHistory 还是 createWebHashHistory。
  3. 检查服务器的静态文件根目录、子目录 base 和 API 路由优先级，避免把 API 请求回退到 HTML。

原因分析 ​

history 模式的路径由浏览器路由器解释，而服务器在刷新时首先接收路径。普通单页应用需要 HTML 回退；预渲染文档站则应寻找对应 HTML 文件，未知文章保持真正 404。两种部署规则不能混用。

修复示例 ​

caddyfile
:8080 {
  root * /srv/app
  handle /api/* {
    reverse_proxy backend:8080
  }
  handle /assets/* {
    file_server
  }
  handle {
    try_files {path} /index.html
    file_server
  }
}

上述配置仅用于普通 SPA。预渲染站点改为 try_files {path} {path}.html {path}/index.html，随后 file_server，并为不存在页面返回 404。修改前备份配置并 validate，失败时恢复备份后 reload。

验证方法 ​

分别检查已知页面直达和刷新、缺失资源、API 错误及未知文章。SPA 的未知业务路由还需前端 NotFound 页面；不要把所有返回 200 都算作通过。

常见误区 ​

盲目使用 /index.html 兜底会把丢失的 JS 返回成 HTML，引发 MIME 错误，并让搜索引擎看到软 404。子目录部署还要同步调整构建 base。

官方参考链接 ​

相关分类：前端 Web · 全部笔记