前端开发这行干久了谁还没被“刷新404”背刺过几回。尤其是 Vue、React 这类单页应用本地联调时一切正常你点菜单从 /login 跳 /dashboard路由切换丝滑得很。可一旦打包部署到服务器上用户在 /login 页面按一下 F5或者直接在地址栏敲回车访问 /login服务器就甩给你一个尴尬的 404。这篇文章就把这个问题的来龙去脉拆开讲清楚包括为什么会出现、怎么排查、几种常见部署场景怎么解决以及那些配完 try_files 之后仍然会踩的新坑。不管你是刚入门的前端新人还是被部署问题反复折腾的“全干工程师”这篇都值得你花几分钟读完。1. 问题本质为什么刷新 /login 会找不到页面1.1 单页应用的路由是“假”的Vue Router 和 React Router 之所以能做到页面“切换”核心机制并不是浏览器真的加载了另一个 HTML 文件而是 JS 在内存里替换了当前视图。你看到的 /login只是浏览器地址栏里的一个变化并没有真正向服务器发出“请返回 login.html”的请求。当用户从 /login 点击跳转到 /dashboard 时前端路由会拦截这次导航阻止默认请求然后靠 JavaScript 渲染新的页面。但刷新就完全不同了。F5 是浏览器级别的动作它会无视前端路由的拦截直接对当前地址栏里的 URL 发起一个真实的 HTTP GET 请求。这时如果服务器上根本没有 /login 这个物理文件或路径对应的资源映射自然就会返回 404。这里可以用一个生活化类比SPA 就像一个装修豪华的展厅展厅里只有一个入口大门index.html但内部用隔断隔出了“登录区”“首页区”“个人中心区”。你在展厅内部走动只是从一个隔断走到另一个隔断不需要出门。可是你一旦走出展厅大门再想回来门口这座楼却只写了“展厅入口”一个门牌你对着墙面喊“我要进登录区”门禁系统当然找不到。1.2 history 模式与 hash 模式的本质差异之所以有的项目刷新没问题、有的项目一刷新就挂最直接的分水岭就是前端路由用的哪种模式。hash 模式下路由信息放在 # 符号后面比如http://example.com/#/login。这个 # 后面的内容浏览器不会发送给服务器服务器只看到http://example.com/所以无论你怎么刷新服务器返回的都是 index.html然后再由前端 JS 读取 hash 值渲染对应页面。history 模式则是利用 HTML5 History API把路径伪装成真实的 URL。好处是地址栏干净没有难看的 #利于分享和 SEO 收录。代价就是一旦你直接访问或刷新一个子路径服务器必须先“聪明地”把所有未知路径都指向 index.html再由前端 JS 接管页面渲染。若服务器没做这个配置就必然出现 404。Vue Router 中这两种模式分别对应createWebHistory()和createWebHashHistory()React Router 则对应BrowserRouter和HashRouter。用 hash 模式刷新问题天然规避因为你根本不会向服务器请求 /login 这个路径。用 history 模式就必须在服务器层做好 fallback否则刷新必挂。1.3 服务器视角Nginx 为什么给你 404很多同学本地用npm run dev跑项目devServer 本身内置了 historyApiFallback所以从没遇到过这个问题。一旦部署换成 Nginx 之后问题就来了。Nginx 的默认行为是收到GET /login请求后先去站点根目录找有没有名为 login 的文件或login/目录。找不到就直接返回 404。它可不知道你的前端是个“单页应用”更不知道应该把 /login 这个请求“转发”给 index.html 去处理。所以问题的根因很简单前端需要的是“路由由 JS 接管”而服务器默认用的是“按文件路径找资源”的逻辑二者认知不一致。我在实际项目中遇到这个问题时的排查顺序是先看路由模式再看服务器配置最后看静态资源路径。三步走完基本能定位九成的问题剩下的要么是跨域配置要么是构建配置的问题。2. 核心排查路径先确认前后端职责边界2.1 三分钟快速复现与基础排查先要能稳定复现问题再去排查。最简单的方式部署完成后打开浏览器访问你的域名根路径比如https://www.example.com/确认首页可以加载。接着打开开发者工具在地址栏输入https://www.example.com/login后回车观察 Network 面板。如果请求 /login 返回的是 404或者返回了某个跟页面无关的“默认欢迎页”那基本可以断定是服务器没有配置 SPA fallback。如果请求返回的是 index.html 的 200但页面却白屏或 JS 报错那问题可能出在静态资源路径或前端路由配置上两者要区分开来。这里有个容易忽略的细节Nginx 的 try_files 一旦配置不当也会出现“首页正常、子路由 404、静态资源 404”三种表现并存的情况。所以排查时不要只看一个页面建议把首页、带参数路由、静态资源三种请求各自测一遍。2.2 检查前端路由模式与 Vite/Webpack 配置打开前端项目找到路由配置文件。Vue 项目通常是router/index.jsReact 项目通常是App.tsx或路由配置文件重点看用createWebHistory还是createWebHashHistoryVue或者BrowserRouter还是HashRouterReact。如果是 hash 模式理论上不应该出现刷新 /login 404 的问题——但注意这里有个例外情况如果你的 Nginx 配置了正则 location 拦截规则恰好匹配上了带 # 之后的字符串也可能出现意想不到的问题。当然这属于少数场景我在第五部分会专门讲。如果是 history 模式检查是否有设置正确的 base 路径。假如项目部署在子目录下比如https://www.example.com/web/那么createWebHistory(/web/)必须和 Nginx 的 root 或者 alias 路径对应上否则即使你配了 try_files资源请求路径仍然会错乱。再检查打包配置Vite 的base参数默认是/。如果你的部署域名是根路径不用改。如果是子路径部署比如/web/Vite 里要配base: /web/Webpack 里则要配output.publicPath: /web/。这个配置如果不一致刷新登录页时 HTML 能返回但里面引用的 JS 和 CSS 全部会请求根路径下的资源然后 404页面直接白屏。2.3 检查静态服务器配置是否接管了路由这一步直接看服务器配置文件。Nginx 最经典也最推荐的配置是location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; }关键就是最后一行 try_files。它的意思是先尝试按真实文件路径找$uri找不到再尝试按目录找$uri/都找不到就把请求重写到/index.html。这样 /login、/dashboard、/user/123 这些“假路径”都会被统一交给 index.html再由前端路由解析出真正的页面。如果你是 Node.js 部署比如用 Express 托管前端产物则要加一个中间件const express require(express); const path require(path); const app express(); app.use(express.static(path.join(__dirname, dist))); app.get(*, (req, res) { res.sendFile(path.join(__dirname, dist, index.html)); }); app.listen(3000);注意这段代码要放在所有 API 路由之后不然会把后端接口请求也拦截到 index.html。Koa 类似需要借助koa-static和自定义中间件实现 fallback。很多人在这一步会犯一个排序错误把app.get(*)放在 API 路由之前结果接口全挂了。这个问题我会在第四部分详细展开。3. 解决方案三种典型部署场景的完整配置3.1 Nginx 部署下的官方解法与参数说明当我们确认是 history 模式 Nginx 的问题后解决方案其实一行 try_files 就能搞定。server { listen 80; server_name www.example.com; root /data/www/myapp/dist; index index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8080; } }这里有两个地方要特别说明第一location /的 try_files 必须写对顺序$uri在前、$uri/中间、/index.html兜底在后不要反过来。第二如果项目里有/api/这样的接口转发一定要用location /api/单独处理并且放在location /之前或者精确匹配否则 try_files 很可能会把 API 请求重写到 index.html导致前端报一堆 “Content-Type 错误” 或者 “Unexpected token ” 之类的诡异问题。另外如果你使用的不是 Nginx 而是 Caddy配置更简单只要一行try_files {path} /index.html。而 Apache 则需要在项目根目录放一个.htaccess文件内容大致是IfModule mod_rewrite.c RewriteEngine On RewriteBase / RewriteRule ^index\.html$ - [L] RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule . /index.html [L] /IfModule这里要注意Apache 的重写条件RewriteCond里有两行第一行排除真实存在文件第二行排除真实存在目录避免图片、CSS、JS 等静态资源被错误重写。这也是 SPA fallback 的通用原则只重写不存在的路径真实文件和目录永远放行。3.2 Node.js 静态服务的 fallback 配置Express 与 KoaNode.js 场景下Express 的配置要记住一个原则静态资源和 API 路由优先SPA fallback 放最后。下面是一份我用过多次、比较稳妥的完整 Express 示例const express require(express); const path require(path); const app express(); // 1. 静态资源 app.use(express.static(path.join(__dirname, dist))); // 2. 后端 API app.use(/api, require(./routes/api)); // 3. SPA fallback必须放最后 app.get(*, (req, res) { res.sendFile(path.join(__dirname, dist, index.html)); }); app.listen(3000, () { console.log(server started at http://localhost:3000); });Koa 的实现需要一些额外的心思因为 Koa 不像 Express 自带路由匹配规则完整写法const Koa require(koa); const path require(path); const serve require(koa-static); const send require(koa-send); const app new Koa(); app.use(async (ctx, next) { if (ctx.path.startsWith(/api)) { return next(); } await next(); }); app.use(serve(path.join(__dirname, dist))); // fallback app.use(async (ctx) { if (ctx.method GET !ctx.path.startsWith(/api)) { await send(ctx, index.html, { root: path.join(__dirname, dist) }); } });这里有个小坑koa-static在处理完静态文件后如果没找到资源会直接调用next()但此时响应头可能已经被修改过容易导致 fallback 逻辑判断混乱。我的经验是fallback 中间件要放在koa-static之后并且显式判断请求方法只有 GET 请求才做 fallback。有些同学直接照抄网上代码把所有请求都 fallback结果 POST 接口也返回 index.html前端会收到一个格式完全不对的响应排查起来非常痛苦。3.3 本地开发与联调环境的配置本地没这个问题不代表不会踩坑。开发环境常见的坑是你用了 history 模式但 devServer 没有开启 historyApiFallback直接访问localhost:5173/login也会白屏。Vite 默认是开启了这个 fallback所以一般没事。但 Webpack 需要显式配置devServer: { historyApiFallback: true, }如果遇到项目有自定义 publicPath 或 base还要加上 rewrite 规则。比如historyApiFallback: { rewrites: [ { from: /^\/web/, to: /web/index.html }, ], }联调环境还有一种比较隐蔽的场景前端项目部署在测试服务器登录成功后跳转到 /dashboard结果再次刷新就 404。这种情况有个特殊的排查方向——是不是测试服没走 Nginx而是用 pm2 直接启动了静态服务器如果是请回到 3.2 节的 Express/Koa 方案。3.4 静态托管平台与 CDN 的特殊处理这类平台的默认策略五花八门处理方式也不一样。GitHub Pages 官方建议使用 hash 路由因为平台不支持重写所有子路径的规则。你可以通过加一个 404.html 文件来实现变通GitHub Pages 找不到页面时会返回 404.html而 404.html 实质上就是你的 index.html 内容。这也是一种可行的方案但只建议在不方便改 Nginx 的仓库里用。Netlify 和 Vercel 这类平台则比较简单Netlify 在public/_redirects文件里写一行/* /index.html 200Vercel 则是在项目根目录放vercel.json{ rewrites: [{ source: /(.*), destination: /index.html }] }CDN 场景更麻烦一点因为 CDN 本身往往不支持 rewrite我的做法是优先在前端源站 Nginx 层把 fallback 配置好CDN 只做缓存加速不要把 CDN 当成唯一的页面服务节点。如果实在只能用纯静态托管那就只能改用 hash 路由或者把业务拆成一个 index.html 多个静态资源目录减少对深层路径的依赖。4. 部署后踩过的坑并不只是改了配置就万事大吉4.1 try_files 配置后接口 404 / 返回 index.html这是一个非常典型的“看似修好了实则更糟”的坑。很多同学给 Nginx 加了try_files $uri $uri/ /index.html之后刷新 /login 确实不 404 了但接口全部开始报错。原因就是location /这个块把所有请求都重写了。假如你的 Nginx 没有单独的location /api/块或者 API 的 location 写在location /后面就会被 try_files 接管。解决的办法就是给 API 单独建 location并且确保它在location /之前location /api/ { proxy_pass http://127.0.0.1:8080/api/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location / { root /data/www/myapp/dist; try_files $uri $uri/ /index.html; }注意proxy_pass结尾是否带斜杠也很关键带斜杠表示去掉/api/前缀再转发不带则保留完整路径转发。这是 Nginx 反向代理的老生常谈但在 SPA fallback 场景下很容易被忽略因为你以为问题全在路由上。4.2 刷新后白屏静态资源找不到刷新 /login 页返回的是 index.html但页面白屏控制台报一堆 JS/CSS 404。这种情况最常见的原因就是资源路径是绝对路径部署在子目录下。比如部署在/web/下面但 HTML 里引用的资源是/assets/index.js浏览器就会去请求/assets/index.js而不是/web/assets/index.js。Vue 项目的处理方式是在vite.config.js里设置base: /web/React 的 create-react-app 则要设置package.json里的homepage字段或者直接改PUBLIC_URL。Webpack 项目需要改output.publicPath。另一个隐藏原因是服务端虽然 fallback 到了 index.html但没有正确设置 Content-Type 头部导致浏览器不认识 HTML 就直接抛错。这种一般出现在自定义 Node 静态服务器中用 Express 的sendFile通常没问题但自己手写fs.readFile时就有踩坑风险。如果你自己写了一个极简静态服务器记得手动设置Content-Type: text/html; charsetutf-8。4.3 刷新后登录态丢失前端要背的锅这是一个经常被栽赃到路由头上的问题。刷新 /login 或者 /dashboard页面虽然正常出来了但用户发现登录态丢了需要重新登录。实际上这不完全是路由的问题。SPA 的登录态通常存在 localStorage 或 cookie 里刷新本身不会清空它。真正的隐患往往是你的 token 只在内存里存了一份比如用了 Redux 或 Pinia 状态管理刷新后内存清空token 就没了。解决方式有两种一是把 token 持久化到 localStorage 或 cookie并在初始化时回填二是借助 OAuth 授权码模式刷新后通过静默令牌刷新接口续期。我见过很多项目在这块偷懒token 放在内存里用户一按 F5 就被踢出来体验极差。这个问题跟 Nginx 配置无关但排查顺序往往会先撞上它。举个实际的例子我去年接手过一个 React 管理后台用户反馈“每次刷新都要重新登录”。一开始团队都以为是路由或 cookie 配置问题排查半天最后发现是开发者在登录成功时把 token 存进了 Redux但没做持久化中间件。刷新后 Redux 初始化token 为空axios 拦截器把它当成未登录直接踢回 /login。这本质上是状态管理设计缺陷但因为它总是在刷新路由后暴露所以很多人都误判成“SPA 路由刷新问题”。4.4 404 状态码对 SEO 和监控的隐性影响即使 try_files 配置正确刷新 /login 返回的仍然是 200 状态码而不是 404。表面上看没有问题了但这带来两个副作用。第一个是 SEO对搜索引擎来说你所有带参数的“假路由”都会返回同一份 HTML如果不做服务端渲染或预渲染搜索爬虫拿到的是空壳页面很多关键词收录效果会很差。如果页面本身不需要 SEO可以不管需要 SEO 的就要考虑 SSR 或预渲染。第二个是监控报警如果你用了 uptime 之类的可用性监控系统只监控 /login 的状态码会发现它永远 200即使前端逻辑已经崩了。我的做法是把监控 URL 设计成/health这样的专用接口由后端返回真实的服务状态而不是依赖前端页面。把这个习惯养成了以后排查线上问题时能省很多沟通成本。4.5 安全与输入校验防止 fallback 被滥用当 try_files 把所有未知路径都指向 index.html 时如果有人拿/api/login、/.env、/config.js之类的敏感路径去探测Nginx 会走到 fallback返回前端页面而不是直接 404。这会给攻击者传递一种错误信号也可能掩盖服务端的目录遍历风险。从安全角度出发合理的配置应该是先精确匹配静态资源、API 和系统关键路径再对剩下的路径做 fallback。或者用正则排除掉敏感扩展名location ~* \.(env|git|log|sql)$ { deny all; return 404; }Nginx 的 location 匹配优先级是精确匹配 正则匹配 前缀匹配理解了这个顺序配置起来才不容易乱。像^~和这些修饰符的使用场景如果你平时接触得少建议先把官方文档过一遍比在网上到处抄配置靠谱得多。5. 常见问题与排查技巧实录5.1 问题速查表现象可能原因快速验证方法解决方案刷新 /login 直接 404服务器未配置 SPA fallback看 Network 中请求返回状态码在 Nginx 配置 try_files刷新 /login 返回 HTML 但白屏静态资源路径错误看 Network 中 JS/CSS 请求是否 404修改 base / publicPath刷新后其他路由正常/login 不行可能是登录页有特殊的跳转逻辑看登录页是否有中间态跳转检查路由守卫和跳转逻辑刷新后登录态丢失token 只存在内存中刷新后查看 localStorage持久化 token 到 localStorage刷新后接口全挂fallback 把 API 请求重写了看接口返回是否为 HTML单独配置 /api locationGitHub Pages 刷新 404平台不支持 rewrite直接访问子路径改用 hash 路由或自定义 404.html这张表是我在实际项目里总结出来的高频问题基本覆盖了 SPA 刷新 404 的主要分支。遇到问题先对照一下能少走不少弯路。5.2 独家经验如何快速定位是前端问题还是服务器问题我自己有一套三分钟定位法。第一分钟打开浏览器 F12看 Network 里 /login 请求返回的 Content-Type。如果是text/html且状态码 200说明前端接管成功如果是text/html且 404说明前端没有接管如果是application/json或者 502、504 之类的状态码基本是接口代理或服务器报错。第二分钟检查返回 HTML 内容。如果是 index.html 的源码说明 fallback 生效如果是一段 Nginx 默认错误页那就是 fallback 没生效。第三分钟直接把 URL 改成 hash 模式访问如果同样路径用/#/login能正常刷新那就能 100% 确认是 history 模式下服务器 fallback 的问题。这套方法不需要翻配置文件只需要浏览器就能定位大概方向很省时间。我在几家公司带新人时都推荐这种思路因为很多新手一上来就改 Nginx改了半天也不知道自己改对了没有反而容易把线上配置搞乱。5.3 为什么有人建议干脆用 hash 模式既然 history 模式这么多坑为什么不干脆全用 hash 模式这也是很多后台管理系统的主流选择。hash 模式的优点很明显部署简单任意静态服务器都能跑没有 fallback 配置需求。代价是地址栏有 #不符合一部分人的审美也不利于 SEO。我的建议是纯业务后台、管理平台、内部系统用 hash 模式完全没有问题省心但对公网开放、需要 SEO 的官网和内容站点必须用 history 模式并在服务器层做好兜底。如果你已经决定用 hash 模式还有一个细节要注意hash 里的中文参数会被浏览器做 URL 编码前后端解析时记得做 decode。5.4 一个容易被忽略的测试构建产物本地预览很多 bug 在 CI/CD 流水线跑完之后才发现一个原因是本地 dev 环境被 devServer 保护得太好。我的建议是每次构建完成后把 dist 产物丢到一个与线上行为一致的静态服务器里本地预览一遍。比如在 dist 目录下执行npx serve -s dist这个命令自带 SPA fallback也可以直接用 Nginx Docker 容器做一次预发布验证。发布前多花五分钟测一下比上线后被用户发现刷新 404 体验要好得多。我在团队里的习惯是把这条写进发布检查清单每次发版前三项必查刷新子路由、静态资源加载、接口代理三关都过才允许合并发布。从第一次被线上“刷新 404”教做人到现在遇到类似问题基本能一眼定位方向我最大的感受是这类问题看起来是配置问题其实考察的是你对“单页应用运行机制”的理解。你只有清楚浏览器在地址栏输入 URL、点击刷新、SPA 内部跳转这三种行为分别发起了什么请求才能准确判断该改前端还是改服务器。如果你在项目里已经遇到了这个问题按我上面说的顺序走一遍——先看路由模式再看服务器配置最后检查资源路径——大概率能一次性解决。最后再分享一个小技巧如果团队里多人负责部署最好把 SPA fallback 能力抽象成公司内部的部署脚手架或者文档甚至直接在 Nginx 模板仓库里统一维护而不是让每个项目自己写配置文件。重复踩同一个坑是对工程师时间的最大浪费。