前端路由折腾了这么多年History 和 Hash 这两兄弟依然是绕不开的话题。不管是刚入行写 Vue 还是 React还是接手老项目要改造总会碰到为什么刷新就 404为什么地址栏带个 #这类灵魂拷问。我最初搞懂这套东西也花了不少时间踩过部署环境的坑也见过线上白屏的血泪现场。所以这篇就把这两种模式从原理到配置、从开发到部署一次讲透把我实际项目里用到的方案和排坑经验都放进来希望对你有帮助。1. 两种模式的核心原理与设计思路1.1 从单页应用的路由问题说起SPA单页应用说白了就是整个站点只有一个 HTML 页面页面切换靠 JavaScript 动态换内容不发新的 HTML 请求。这种模式下路由本质上是前端自己维护的一个状态。但用户有几个绕不开的需求地址栏 URL 要变、浏览器前进后退要好用、刷新之后页面不能丢。于是就有了路由的两种实现方式。Hash 模式是曲线救国的思路URL 里加个#后面的部分就是 hash。http://example.com/#/user/123这个地址里真正发给服务器的请求只是http://example.com/hash 部分纯粹是浏览器本地行为。#/user/123的变化不会让浏览器向服务器发请求这就避开了服务器配置的麻烦。开发环境下用起来特别顺手双击 HTML 文件都能跑。History 模式则走了正道利用 HTML5 History API 里的pushState和replaceState把 URL 改成http://example.com/user/123这种干净地址同样不触发页面刷新和服务器请求。但问题来了用户在/user/123刷新时浏览器会向服务器真的请求这个路径。服务器如果没配置好直接给你返回 404。1.2 状态管理与路由切换的内部机制理解这两种模式不能只停在表面得看看它们底层的状态维护逻辑。Hash 模式的核心是hashchange事件。当你通过location.hash修改地址时浏览器会往历史栈里压入一条记录同时触发hashchange事件。前端路由监听这个事件读取location.hash解析出对应路由再渲染对应组件。这里的细节是hash 变化会留下历史记录所以前进/后退天然可用而且 hash 变化时页面本身不重新加载组件渲染性能上也少了一次 HTML 拉取。History 模式则调用了history.pushState(state, title, url)。这个方法会改变地址栏 URL 并且压入历史栈但同样不触发页面刷新也不会发请求。配合popstate事件用户点浏览器前进/后退时触发前端就能感知到路由变化。但需要注意pushState本身不会触发popstate所以路由库内部需要在调用pushState后手动执行匹配和渲染逻辑。我在项目里更喜欢用自己的话总结Hash 模式是地址栏的尾巴自己玩History 模式是地址栏整条自己玩但服务器也得陪着玩。这个陪伴关系就是配置的来源。2. 关键特性全面对比与选型分析2.1 核心差异对比表这张表我压了很多次基本覆盖了日常开发需要关注的点。对比维度Hash 模式History 模式URL 示例/index.html#/user/1/user/1地址颜值丑带 # 号美观、语义化刷新页面正常始终加载index.html需服务端回退配置否则 404服务端配置无需特殊处理必须配置 history 回退浏览器支持IE8 无压力IE10需支持 History APISEO 友好度较差爬虫不执行 JS 时看不到内容相对友好配合 SSR/预渲染更佳开发调试本地直接开文件就能测需本地起服务并配置回退指向首页移动端兼容部分老 WebView 兼容性好基本没问题但微信等内置浏览器需验证埋点统计需自定义处理 hash 参数与传统 URL 统计完全兼容看这张表能发现Hash 的最大杀手锏是免配置、容忍度极高History 的核心价值是地址好看 SEO 有救 统计干净。除了这些我再补两个容易被忽略的差异。2.2 微信登录回调与 OAuth 跳转的隐藏坑开发过微信网页应用的人应该都有体会微信 OAuth 回调会拼接一个code参数类似https://example.com/user?codexxx。如果你用的是 Hash 模式URL 会变成https://example.com/index.html#/user?codexxx——注意code 是嵌在 hash 里的服务端和后端取参时都得解析 hash。而 History 模式下 code 就是正常 query 参数后端重定向时也好处理。这里有个典型的坑微信授权回调域名只认路径前缀如果拿到的不是完整 URL 或者code被 hash 隔断后端的request.query.code会直接是undefined。我处理过一个项目前端拿到 hash 里的 code 再手动拼到 header 里传给后端正因为这点绕路排查了很久。选型的时候如果确定要做微信生态页面History 模式从入参角度会干净很多。2.3 动态标题和分享图配置的差异网页在微信里分享时需要动态设置document.title和缩略图。Hash 模式下URL 差异集中在#后分享出去的链接在部分老版本微信里可能丢失 hash 后的部分导致分享出去的地址是错的。History 模式下 share 地址就是完整路径前端的分享逻辑也更顺畅。当然这些场景的分量取决于你的用户群体。写 toB 后台管理系统的用户不分享、不做 SEO那 Hash 完全够用toC 落地页、内容站、需要微信裂变的我建议优先 History。别的博主喜欢喊推荐 History我一般画一条线部署在自己能完全掌控的服务上且需要更多前端掌控力才考虑 History否则 Hash 省心得多。2.4 从项目实践看选型逻辑我自己的经验判断选择哪套方案按下面这个顺序过一遍就行。第一服务器或托管平台是否支持 rewrite重写规则。Nginx 一条try_files就能解决但如果你用的是静态托管比如某些 OSS 静态网站托管、GitHub Pages配置 rewrite 有时候做不到这时 Hash 模式几乎是唯一选择。当然 GitHub Pages 现在也支持 404 页面的小技巧但可靠性与正规 rewrite 仍有差距。第二现有项目是要重构还是新项目。老项目如果全是 Hash 模式路由链接已经被各种渠道收录切到 History 意味着所有 URL 都变了301 重定向和埋点全要跟着改工作量巨大。这时我建议保持现状只在新模块做渐进式改造。第三团队对 History 原理的掌握程度。不是每个团队都愿意在 Nginx 配一条try_files也不是每个人都理解base配置和子路径部署。如果团队技能偏前端不想涉足运维Hash 模式更稳妥。我见过不少团队在 History 模式下上线后因为运维和前端没有对齐导致用户深链刷新一片 404 的惨剧。第四产品对 URL 语义的诉求。如果 URL 要拿去分享、要对用户展示可读路径、要和后端 REST 接口路径做映射History 就值得投入。3. 实操配置从 Vue Router 到 Nginx 部署3.1 Vue Router 中的模式配置与 base 路径处理现在 Vite 创建 Vue 3 项目默认就是 History 模式因为它美观且开发环境自带回退。想切 Hash 模式在router/index.js里改一行就行。import { createRouter, createWebHistory, createWebHashHistory } from vue-router // History 模式 const router createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes }) // Hash 模式 const router createRouter({ history: createWebHashHistory(), routes })注意createWebHistory(import.meta.env.BASE_URL)里的参数BASE_URL 对应 Vite 的base配置。如果项目部署在子路径下比如https://example.com/admin/base就要配置成/admin/否则资源路径全挂。这一条也是老生常谈但最常出错的。React Router v6 里的写法类似BrowserRouter basename/admin App / /BrowserRouter HashRouter App / /HashRouter3.2 开发环境的默认回退与代理配置用 Vite 开发时vite.config.js里往往配了代理后端接口走/api。前端路由在开发服务器上是默认支持 History 回退的所以本地开发体验没问题。但有一个细节Vite 的代理 target 如果指向了跨域后端且你开启了changeOrigin会导致浏览器 Cookie 的域名变化登录态失效。我遇到过一次排查半天发现是代理配置引起的后来把cookieDomainRewrite配置上才解决。// vite.config.js export default defineConfig({ plugins: [vue()], server: { proxy: { /api: { target: http://localhost:3000, changeOrigin: true, cookieDomainRewrite: localhost, } } } })如果你把页面放在https://example.com/project-name/子路径下开发环境的 base 也要同步配置base: /project-name/否则打包后资源引用路径完全是错的。3.3 Nginx 配置 History 模式与静态资源缓存这是整个配置环节最核心的部分。上生产前你要理解 Nginx 的静态资源服务逻辑。下面是 I 实际项目里常用的配置server { listen 80; server_name example.com; root /var/www/myapp; index index.html; # 核心所有非真实文件的请求都回退到 index.html location / { try_files $uri $uri/ /index.html; } # 静态资源带 hash 文件名可以长期缓存 location /assets/ { expires 30d; add_header Cache-Control public, immutable; } # 明确不缓存的 HTML 入口 location /index.html { add_header Cache-Control no-cache, no-store, must-revalidate; } }try_files $uri $uri/ /index.html这条指令的含义是先检查$uri这个文件是否存在不存在就看目录目录也不存在就把请求交给/index.html。这就保证了浏览器访问/user/123时Nginx 会把index.html返回给前端由前端路由接管。注意配置顺序要放在location /块里且要在任何其他 location 之前否则可能被干扰。3.4 Node.js 服务端配置Express/Koa/Next.js如果你用 Node.js 自己起了一个静态服务Express 的处理方式是这样的const express require(express) const path require(path) const app express() // 静态资源 app.use(express.static(path.join(__dirname, dist))) // 所有非 /api 的 get 请求回退到 index.html app.get(/^(?!\/api).*/, (req, res) { res.sendFile(path.join(__dirname, dist, index.html)) }) app.listen(3000)这里用正则排除/api前缀防止后端接口也被回退到 HTML。你也可以用connect-history-api-fallback这个库简化处理const history require(connect-history-api-fallback) app.use(history()) app.use(express.static(path.join(__dirname, dist)))顺序上history()中间件要在static之前否则静态资源匹配不到时也会套到回退逻辑里导致 JS、CSS 请求也返回 HTML。这是个非常隐蔽的错误浏览器控制台会报 MIME type 错误页面白屏但服务器日志里看不出任何异常。3.5 特殊场景Docker Nginx 组合部署Docker 部署现在很常见前端容器里就是一个 Nginx。需要把nginx.conf挂载进去并把try_files写进 server 块。需要注意容器内的路径是/usr/share/nginx/html你要在docker run时用-v把本地dist目录挂载进去或者在构建镜像时用多阶段构建把打包产物 COPY 进去。FROM node:18-alpine AS build WORKDIR /app COPY package.json ./ RUN npm install COPY . . RUN npm run build FROM nginx:alpine COPY --frombuild /app/dist /usr/share/nginx/html COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80 CMD [nginx, -g, daemon off;]这样构建出来的镜像起来就是一个带 History 回退的前端站点。我习惯把nginx.conf单独放一个文件改配置不用重新构建镜像只重新起容器挂载就行。3.6 KaTeX 渲染失败的隐藏关联有人可能会疑惑KaTeX 渲染失败也归前端路由管吗其实不是。但我在排查一个 Math 渲染页面时发现了一个间接关联项目切到 History 模式后深链接直接访问数学文档页面Nginx 回退到index.html没毛病但是文档内容是通过异步请求从静态 JSON 里加载的而 JSON 文件路径在子路径部署时写错了导致数据没取到KaTeX 自然没有内容可以渲染。所以如果你的页面出现某种渲染失败先看网络请求是不是真的返回了内容再看路由模式是不是影响到了资源路径拼接。经验是前端路由模式改动之后把所有网络请求的 URL、资源路径全部过一遍很多问题不是出在路由本身而是出在路径语义被你改坏了。4. 常见问题与排查技巧实录4.1 刷新 404 的核心逻辑与应对这几乎是 History 模式最经典的坑。场景用户在https://example.com/user/123按 F5Nginx 找不到/user/123文件返回 404。你第一反应是配置try_files但还有几种非典型情况Nginx 里配置了多个 location 优先级导致 try_files 没生效比如你写了一个location /user { ... }这个 location 内部没有配置回退逻辑请求直接 404。反向代理层没有透传你在 CDN 层比如 Cloudflare、阿里云 CDN做了源站回源但 CDN 缓存了 404 页面刷新依然 404。此时需要清理 CDN 缓存或者设置源站 404 时回源刷新策略。服务端语言自己做的路由拦截比如你用 Express 并且先调用了app.get(/user/:id, ...)又被前端路由接管冲突了。处理思路先用curl -I https://example.com/user/123看响应头是哪个层返回的 404定位到具体环节再对症下药。4.2 部署子路径下资源全部 404 的根因这个问题特别典型。项目部署在https://example.com/foo/子路径下首页能打开但点击路由跳到/bar刷新后白屏或者资源加载 404。根因通常在两个地方第一Vite 的 base 没配置。如果你用相对路径引用资源在 History 模式下子路由的 URL 变成了/foo/bar相对路径./assets/index.js会被解析成/foo/assets/index.js这是对的但如果你在入口 HTML 里写了绝对路径/assets/index.js它就被解析成https://example.com/assets/index.js自然 404。解决方案是统一使用import.meta.env.BASE_URL拼接路径Vite 会在打包时自动处理。第二后端静态资源服务没做路径前缀处理。如果前端资源是由某个后端服务统一托管的需要让服务正确支持/foo/assets/路径很多后端框架需要额外配置前缀。一个稳妥的做法是所有资源引用使用相对路径同时 Nginx 的try_files做完整的回退location /foo { try_files $uri $uri/ /foo/index.html; }4.3 Hash 模式特有坑锚点定位与埋点统计冲突Hash 模式有一个容易被忽略的问题Hash 本身就用于页面内锚点定位比如#section-1需要页面滚动到对应位置。如果你用 Hash 做路由URL 的 hash 就被路由占用了页面内锚点定位会冲突。解决方案是不要用原生锚点实现滚动定位用scrollIntoView JavaScript 方法。或者路由路径上不要出现#section这种结构改用 query 参数实现。埋点统计上Hash 模式也有个烦人之处路由变化只反映在 hash 部分而大部分第三方统计脚本默认只上报页面加载时的完整 URLhash 变化后不会自动补一条 PV。所以你需要手动监听路由变化在afterEach钩子里上报。Vue Router 里可以这样router.afterEach((to, from) { if (typeof window._hmt ! undefined) { // 百度统计 window._hmt.push([_trackPageview, to.fullPath]) } // 友盟、GA 等类似 })实际项目里我甚至遇到过统计系统把#后面的字符截断的情况导致上报页面路径缺失。所以如果统计是你的核心需求History 模式省心不少。4.4 常见问题速查表我把日常工作中最高频的几类问题整理成一张表方便你遇到时快速定位。症状可能原因解决方案刷新 /user/123 返回 404服务端没有配置回退到 index.htmlNginx 加try_files $uri $uri/ /index.html;首页正常点击路由后资源 404资源引用用了绝对路径或 base 配置错误Vite 配置base统一用import.meta.env.BASE_URL页面白屏控制台报 MIME type 错误Nginx 把 JS/CSS 请求也回退到 index.htmlhistory()中间件放在static之前微信/QQ 内置浏览器分享链接丢失路由老 WebView 对 URL 支持不佳兼容性优先用 Hash 模式或升级 History 分享处理Hash 模式下锚点定位失效hash 被路由占用用scrollIntoView代替锚点统计后台没有路由切换数据路由变化未触发页面浏览上报在 router.afterEach 中手动上报部署子路径后接口请求 404接口前缀未带 base 路径用import.meta.env.BASE_URL api/...或配置代理登录后跳转回跳地址丢失参数回调地址拼接错误hash 和 query 混用在存储和回跳时单独处理 hash 内参数4.5 排查工具和工作流分享排查路由问题时我一般按这个顺序来第一看网络面板。F12打开 Network刷新页面看请求的到底是/user/123还是/index.html响应状态码是多少Content-Type 是 text/html 还是 application/json。如果 JS 请求返回了 HTML基本就是回退配置放错了位置。第二看服务端日志。不是所有问题都能在前端看到Nginx 的 access.log 和 error.log 里可以看到实际请求的路径、响应码、upstream 转发到哪。特别是多层代理时必须逐层确认。第三减少变量。只改一个配置验证一次。不要同时改 Nginx 和前端 base否则出了问题不知道是哪边引起的。我在排查一个 Vue 项目时还发现线上 Nginx 配置有问题但测试环境一直正常。后来发现是 Nginx 缓存了旧的配置文件改了不生效。遇到配置不生效先nginx -t验证语法再nginx -s reload还不行就确认容器里的配置真的被替换掉了。这一步虽然基础但很多人浪费了不少时间。5. 项目改造迁移实战与 SEO 取舍5.1 从 Hash 平滑迁移到 History 的步骤老项目从 Hash 迁到 History最怕的是线上用户收藏的旧链接全部失效。我做过一次完整迁移流程是这样的。第一步确认服务端回退能力。和运维对齐在测试环境 Nginx 先加上try_files用 curl 模拟访问几个典型路径验证。第二步替换路由模式。Vue Router 中createWebHashHistory()替换为createWebHistory()同时检查所有router.push、router-link的写法——一般不用动路由库内部都兼容。第三步处理带参数链接。Hash 模式下/index.html#/user/1?tabinfoHistory 模式下变成/user/1?tabinfo。链接语义一样但参数位置变了后端或前端代码里所有手动解析 URL 的地方都要改。第四步处理埋点和统计。上线后对比新旧版本统计数据的差异特别要关注直接访问深链的流量是否回落。第五步灰度发布。先在灰度环境上跑用线上小程序几分流量验证观察日志里的 404 率和后端报错率再全量切。迁移完成后别忘了给旧链接做 301 跳转。Hash 模式的老地址https://example.com/#/user/1不会自己跳到/user/1需要在index.html里注入一段 JS检测到 hash 就重定向否则老用户点收藏链接会落在首页体验很差。// 兼容 hash 老链接 if (location.hash.startsWith(#/)) { location.replace(/ location.hash.slice(2)) }这段脚本要放在路由初始化之前最好直接内联在index.html的head里。5.2 改造过程中的数据回放与用户影响评估改造前一定要看你埋点/统计里的落地页路径分布。Hash 模式下统计系统拿到的路径五花八门有的上报#/有的上报#/user/1有的把整个 hash 截断了。你在迁移前后做对比时不能只看 PV 总量要看非首页路径的访问量是否趋势突变。我见过有项目迁移 History 后SEO 流量短时间急剧下滑原因就是搜索引擎索引的旧 hash URL 全失效了而新 URL 还没被收录。这个阵痛期只能靠时间和站点地图补录来缓解没有捷径。5.3 SEO 的真相History 不是万能药很多博主会说History 模式更利于 SEO这话对但不完全对。搜索引擎爬虫最终看到的是 HTML 内容而 SPA 的 HTML 只是一个空壳。如果你不配 SSR、不配预渲染爬虫拿到的页面和用户看到的完全是两回事模式换成 History 对 SEO 的提升极其有限。真正解决 SEO 的方案是 SSR服务端渲染、SSG静态生成或预渲染prerender。History 模式只是让 URL 语义化让路径能被正确索引内容还得靠 SSR 或预渲染来喂给搜索引擎。所以如果你的站点需要 SEO选型逻辑应该是确认要 SSR/SSG 吗如果要那用 History如果只是内部工具站搜索引擎根本不会来用什么模式无所谓Hash 就够了。我做过一个内容站最初用 History SPA百度收录了页面但全是空内容后来上了预渲染收录和流量才逐步恢复。这里有个经验预渲染不能覆盖所有动态路由必须是可枚举的路径才能预渲染动态详情页还是得 SSR 或走动态渲染方案。5.4 更细致的折中方案混合模式与动态渲染项目里有时候不一定要二选一。我早年维护过一个平台后台管理系统用 Hash部署简单前台内容站用 History配合 SSR/预渲染。两者在同一个域名下不同路径共存Nginx 分别处理# 管理后台Hash 模式不需要回退 location /admin/ { alias /var/www/admin/; try_files $uri $uri/ /admin/index.html; } # 前台站点History 模式需要回退 location / { try_files $uri $uri/ /index.html; }还有一种动态渲染服务端根据 User-Agent 判断是爬虫还是普通用户爬虫给完全渲染后的 HTML普通用户给 SPA。这个方案比纯 SSR 简单但性能和成本要评估。我这几年看下来大多数中小型站点用静态托管 History 预渲染就能满足要求不必一上来就上重 SSR。6. 周边配套开发调试、构建部署与团队协作6.1 本地开发时的代理与路径模拟开发环境下如果你用的是 Viteserver.proxy可以把接口代理到后端这样前端地址和后端地址分离不会触发跨域。但这里有个细节代理只对开发服务器生效打包部署后 Nginx 也要有对应的反向代理配置。location /api/ { proxy_pass http://backend-server:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }我建议前端项目从第一天就把/api前缀约定好后端接口统一挂在/api下。这样开发用 Vite 代理部署用 Nginx 代理逻辑一致切换环境只改一份配置。6.2 构建产物检查清单打包后我一般会做一轮人工检查别急着上传服务器打开dist/index.html看 JS/CSS 引用路径是相对路径还是绝对路径。dist目录里跑一个本地静态服务器npx serve dist或python3 -m http.server模拟线上访问点击所有主要路由刷新验证是否有 404。用curl请求线上某个深层路由的 URL确认返回的 HTML 是index.html还是 404 页面。这一步能提前拦住 80% 的线上事故。6.3 团队协作里的路由规范团队协作上路由模式的切换往往还牵涉到后端 API 的路径设计。我遇到过前后端路径语义冲突前端router.push(/user/1)后端接口恰好也有GET /user/:id某些场景下服务端会拦截本应发给前端的路由请求。所以团队里最好有个路由清单文档前端路由路径统一用名词复数后端接口统一带/api前缀两者永远不打架。另外路由模式的文档要写清楚谁能改、改了之后要验证什么。我在团队里建过一个部署前检查项如果改动了路由模式或 Nginx 配置必须有 3 个环境验证通过本地、测试、预发并且在线上回退方案里注明如何快速把模式回滚成 Hash。6.4 现代框架里的路由配置速查最后放一份 Vue 3/React 常用配置对照覆盖开发中最常见的一些情况。Vue Router 4createWebHistory(process.env.BASE_URL)对应 History 模式createWebHashHistory()对应 Hash 模式createMemoryHistory()是 Node 环境/测试用的不改变 URLReact Router v6BrowserRouter basename/admin对应 History 模式HashRouter对应 Hash 模式MemoryRouter用于测试和非浏览器环境Nuxt 3 和 Next.js 则把路由模式封装了默认就是 History 风格用户不需要关心。但部署时依然要注意服务端回退配置Next.js 有对应的rewrites和headers配置项。// next.config.js module.exports { async rewrites() { return [ { source: /:path*, destination: /index.html } ] } }这份东西适合存到团队文档里作为前端基础设施的一部分。每次有新人入坑我直接把这份配置和排坑表甩给他省下不少沟通成本。回到主题本身Hash 和 History 没有绝对的优劣只有合不合适的场景。小团队内部系统、托管平台受限的项目Hash 就是效率最高的选择面向公网、需要分享和 SEO 的产品就咬咬牙把 History 的服务端配置和迁移工作做好。我在实际项目里的体会是排查路由相关问题的时候先搞清楚请求链路里每一层是什么角色——浏览器、CDN、Nginx、后端、前端路由库——再逐层确认配置远比靠猜快得多。希望这篇文章能帮你把路由这块踩过的坑都填平也欢迎你把自己遇到的奇葩问题拿出来一起讨论。