企业官网建设流程全解析

前端开发这行干久了，谁还没被“刷新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.js，React 项目通常是App.tsx或路由配置文件，重点看用createWebHistory还是createWebHashHistory（Vue），或者BrowserRouter还是HashRouter（React）。

如果是 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 与 Koa）

Node.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 200

Vercel 则是在项目根目录放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; charset=utf-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 问题速查表

这张表是我在实际项目里总结出来的高频问题，基本覆盖了 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 模板仓库里统一维护，而不是让每个项目自己写配置文件。重复踩同一个坑，是对工程师时间的最大浪费。