Vue Router 的三种历史模式详解

📌 核心概览

在 Vue.js 单页应用（SPA）中，vue-router 提供了三种不同的 历史模式 来管理路由导航和 URL 显示方式。每种模式适用于不同场景，理解其原理与配置是构建现代前端应用的关键。

模式	创建函数	特点	SEO 友好	服务器要求
Hash 模式	`createWebHashHistory()`	使用 `#` 分隔真实路径与路由信息，兼容性好	❌ 不友好	无
HTML5 模式	`createWebHistory()`	正常 URL 形式，美观且利于 SEO	✅ 友好	需要回退配置
Memory 模式	`createMemoryHistory()`	不依赖浏览器环境，适合 SSR 和测试环境	⚠️ 视情况	无

🔍 一、Hash 模式（哈希模式）

🎯 基本概念

利用 URL 中的 # 后面的部分（即 hash）来模拟页面跳转。
浏览器不会将 # 后的内容发送到服务器，因此无需后端支持。

💡 示例代码

javascript 复制代码

import { createRouter, createWebHashHistory } from 'vue-router'

const router = createRouter({
  history: createWebHashHistory(),
  routes: [
    { path: '/home', component: Home },
    { path: '/about', component: About }
  ]
})

访问地址如：https://example.com/#/home

✅ 优点

兼容老版本浏览器（IE9+）
无需服务器额外配置
开发调试方便

❌ 缺点

URL 不美观，带有 #
对 SEO 不友好（搜索引擎可能忽略 hash 内容）

🔍 二、HTML5 模式（浏览器历史记录模式）

🎯 基本概念

使用 HTML5 的 history.pushState() API 实现真实的 URL 路径。
URL 更加"正常"，例如：https://example.com/user/123

💡 示例代码

javascript 复制代码

import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/user/:id', component: UserComponent }
  ]
})

⚠️ 关键问题：404 错误

当用户直接访问 /user/123 时，请求会发送给服务器。如果服务器没有对应资源，则返回 404。

✅ 解决方案：Fallback 回退机制

所有非静态资源请求都应返回 index.html，交由前端路由处理。

常见服务器配置示例：

服务器	配置方法
nginx

javascript 复制代码

location / {
  try_files $uri $uri/ /index.html;
}

| Apache |

| Express (Node.js) | 使用中间件：

javascript 复制代码

const history = require('connect-history-api-fallback');
app.use(history());

| Firebase Hosting | 在 firebase.json 添加：

javascript 复制代码

{
  "hosting": {
    "rewrites": [
      { "source": "**", "destination": "/index.html" }
    ]
  }
}

| Netlify | 创建 _redirects 文件：

html 复制代码

/* /index.html 200

| Vercel | 创建 vercel.json：

javascript 复制代码

{ "rewrites": [{ "source": "/:path*", "destination": "/index.html" }] }

✅ 优点

URL 美观，符合现代 Web 标准
利于 SEO 优化
用户体验更自然

❌ 缺点

必须配合服务器正确配置
配置不当会导致 404

🔍 三、Memory 模式（内存模式）

🎯 基本概念

将路由状态保存在内存中，不依赖浏览器的 URL 或历史栈。
完全由 JavaScript 控制导航。

💡 示例代码

javascript 复制代码

import { createRouter, createMemoryHistory } from 'vue-router'

const router = createRouter({
  history: createMemoryHistory(),
  routes: [
    { path: '/login', component: LoginComponent }
  ]
})

// 手动触发初始导航（必须！）
router.push('/login')

✅ 适用场景

服务端渲染（SSR）
Node.js 后端环境
单元测试或自动化脚本
移动端 WebView 或 Electron 应用（可选）

❌ 注意事项

浏览器中无法使用前进/后退按钮
页面刷新后路由状态丢失
URL 不更新，不利于分享

🧩 补充知识点：处理 404 页面

由于 HTML5 模式下所有路径都被重定向到 index.html，服务器不再返回 404，因此需要在前端实现通用匹配路由。

✅ 前端万能路由配置

javascript 复制代码

const routes = [
  { path: '/', component: Home },
  { path: '/about', component: About },
  // 通配符路由必须放在最后
  { path: '/:pathMatch(.*)*', name: 'NotFound', component: NotFoundComponent }
]

也可以解构参数：

javascript 复制代码

// 访问 /not-found 时
this.$route.params.pathMatch // "not-found"

🔄 更佳实践（SSR 场景）

在服务端预先用路由器匹配 URL：

匹配成功 → 渲染页面
匹配失败 → 返回 HTTP 404 状态码

查看 Vue SSR 文档获取更多细节。

📊 对比图表：三种历史模式一览表

特性	Hash 模式	HTML5 模式	Memory 模式
是否改变真实 URL	否（仅改 hash）	是	否
是否需要服务器配置	否	是	否
支持前进/后退	是	是	否（除非手动模拟）
SEO 友好性	差	好	取决于上下文
适用环境	浏览器	浏览器	浏览器 / SSR / 测试 / Node
URL 示例	`/#/user/1`	`/user/1`	（无变化）
初始化是否需手动 push？	否	否	是

🧠 知识点详解

下列为解决上述内容所涉及的核心知识点：

1. HTML5 History API

通过 $window.history.pushState() 动态修改 URL 而不刷新页面，是实现 HTML5 模式的基础。它允许 SPA 拥有"真实"路径。

2. URL 重写与回退机制

服务器需配置将所有未命中静态资源的请求指向 index.html，从而交由前端路由处理，避免 404 错误。

3. 通配符路由匹配

使用 /:pathMatch(.*)* 捕获任意未知路径，在前端展示 404 页面，弥补服务器回退带来的错误掩盖问题。

✅ 总结建议

使用场景	推荐模式	理由
普通生产环境 Web 应用	✅ HTML5 模式	更好的用户体验和 SEO
快速开发、演示或无后端支持项目	✅ Hash 模式	零配置，开箱即用
SSR、测试、Node.js 环境	✅ Memory 模式	独立于浏览器环境，便于控制
移动 Hybrid 应用	⚠️ Hash 或 Memory	根据容器能力选择

📎 附加提示

若部署在子目录（如 /my-app/），记得设置 base: '/my-app/'：

javascript 复制代码

const router = createRouter({
  history: createWebHistory('/my-app/'),
  routes: [...]
})

构建工具（Vue CLI / Vite / Nuxt）通常已集成相关插件，但仍需手动配置服务器规则。
使用 CI/CD 部署时，确保 _redirects 或 vercel.json 等文件包含在构建输出中。