Vue3 中 createWebHistory 和 createWebHashHistory 的区别

'# Vue3 中 createWebHistory 和 createWebHashHistory 的区别

一、背景与问题

在 Vue3 的项目中，开发人员常常需要根据业务需求选择合适的路由模式。Vue Router 提供了 createWebHistory 和 createWebHashHistory 两种创建历史记录的方式，分别对应 HTML5 历史模式和哈希模式。

这两种模式的本质区别在于：HTML5 历史模式通过 pushState 和 replaceState API 实现 URL 的动态更新，而哈希模式则通过 URL 中的 # 段实现路由切换。这种差异会显著影响开发体验、SEO 优化、服务器配置以及 URL 的美观性。

在实际开发中，开发人员常常遇到以下问题：

为什么刷新页面后会 404？
哈希模式下 URL 显示不美观？
如何在服务器配置中处理这两种模式？
哪种模式更适合单页应用（SPA）？

本文将深入解析这两种模式的底层原理、实际使用场景、性能影响以及常见陷阱。

二、基本原理

1. HTML5 历史模式（`createWebHistory`）

HTML5 历史模式依赖 pushState 和 replaceState API，允许在不刷新页面的情况下修改 URL。其核心原理是：

URL 变化不会触发页面刷新（避免全量重新加载）
URL 中的路径和参数被直接写入地址栏
路由变化通过 hashchange 事件监听

优点：

URL 看起来像传统网站（如 /about）
无需额外配置服务器
更符合现代 SPA 的开发习惯

缺点：

需要服务器正确配置（否则刷新会 404）
不兼容 IE11（需要 polyfill）
需要额外处理浏览器历史记录的管理

2. 哈希模式（`createWebHashHistory`）

哈希模式通过 URL 中的 # 段实现路由，其核心原理是：

URL 中的 # 后的内容作为路由路径（如 #/about）
路由变化通过 hashchange 事件监听
页面刷新时，# 后的内容会作为查询参数传递给服务器

优点：

无需服务器配置（即使刷新也能正常工作）
兼容性好（支持 IE8+）
不需要额外处理历史记录

缺点：

URL 不美观（包含 # 段）
SEO 优化不如 HTML5 模式友好
在移动端可能影响用户体验

三、环境准备

1. 项目依赖

确保项目中安装了 Vue3 和 Vue Router：

npm install vue@next vue-router@4

2. 开发环境

需要支持 HTML5 历史模式的开发服务器配置（如 Vite 或 Webpack）。对于哈希模式，无需额外配置。

四、核心实现

1. 基础用法（代码示例）

示例 1：创建 HTML5 历史模式的路由

// main.js
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import App from './App.vue'

const routes = [
  { path: '/', component: () => import('./views/Home.vue') },
  { path: '/about', component: () => import('./views/About.vue') }
]

const router = createRouter({
  history: createWebHistory(),
  routes
})

createApp(App).use(router).mount('#app')

关键点：

createWebHistory() 创建 HTML5 历史记录对象
路由路径直接写入 URL（如 /about）
刷新页面时需确保服务器正确配置（否则会返回 404）

示例 2：创建哈希模式的路由

// main.js
import { createApp } from 'vue'
import { createRouter, createWebHashHistory } from 'vue-router'
import App from './App.vue'

const routes = [
  { path: '#/', component: () => import('./views/Home.vue') },
  { path: '#/about', component: () => import('./views/About.vue') }
]

const router = createRouter({
  history: createWebHashHistory(),
  routes
})

createApp(App).use(router).mount('#app')

关键点：

createWebHashHistory() 创建哈希模式的路由对象
URL 中的 # 后的内容作为路由路径（如 #/about）
刷新页面后仍能正常工作（无需服务器配置）

示例 3：动态切换路由模式

// main.js
import { createApp } from 'vue'
import { createRouter, createWebHistory, createWebHashHistory } from 'vue-router'
import App from './App.vue'

const routes = [
  { path: '/', component: () => import('./views/Home.vue') },
  { path: '/about', component: () => import('./views/About.vue') }
]

// 动态切换路由模式
const isHashMode = window.location.hash ? true : false
const history = isHashMode 
  ? createWebHashHistory() 
  : createWebHistory()

const router = createRouter({
  history,
  routes
})

createApp(App).use(router).mount('#app')

关键点：

根据当前 URL 是否包含 # 动态选择路由模式
哈希模式更适合需要兼容旧浏览器的场景
HTML5 模式更适合需要美观 URL 的现代应用

五、完整案例

1. 一个完整的 Vue3 应用（HTML5 模式）

项目结构

project/
├── index.html
├── main.js
├── App.vue
├── views/
│   ├── Home.vue
│   └── About.vue
└── router/
    └── index.js

`index.html`

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Vue3 History Mode</title>
</head>
<body>
  <div id="app"></div>
</body>
</html>

`main.js`

import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import App from './App.vue'
import { routes } from './router/index'

const router = createRouter({
  history: createWebHistory(),
  routes
})

createApp(App).use(router).mount('#app')

`App.vue`

<template>
  <div>
    <nav>
      <router-link to="/">Home</router-link> |
      <router-link to="/about">About</router-link>
    </nav>
    <router-view />
  </div>
</template>

`router/index.js`

export default [
  { path: '/', component: () => import('./views/Home.vue') },
  { path: '/about', component: () => import('./views/About.vue') }
]

`views/Home.vue`

<template>
  <h1>Home Page</h1>
</template>

`views/About.vue`

<template>
  <h1>About Page</h1>
</template>

运行效果：

访问 http://localhost:8080/ 显示 Home 页面
访问 http://localhost:8080/about 显示 About 页面
刷新页面后仍能正常显示内容（需服务器配置）

六、源码解析

1. `createWebHistory` 的实现原理

Vue Router 的 createWebHistory 实际上是调用了 history.createHistory() 方法，其底层逻辑如下：

// vue-router/src/history/web.ts
export function createWebHistory(base = '/') {
  const history = window.history
  const pushState = history.pushState
  const replaceState = history.replaceState

  function createHistory() {
    return {
      // 基础路径
      base,
      // 捕获路由变化
      onPush: (url) => {
        if (pushState) {
          pushState(null, '', url)
        }
      },
      onReplace: (url) => {
        if (replaceState) {
          replaceState(null, '', url)
        }
      },
      // 其他方法...
    }
  }

  return createHistory()
}

关键点：

使用 pushState 和 replaceState 实现 URL 的动态更新
需要服务器配置为处理 / 路径的静态资源（否则刷新会 404）

2. `createWebHashHistory` 的实现原理

createWebHashHistory 的底层逻辑如下：

// vue-router/src/history/web.ts
export function createWebHashHistory(base = '/') {
  const history = window.location
  const pushState = history.pushState
  const replaceState = history.replaceState

  function createHistory() {
    return {
      // 基础路径
      base,
      // 捕获路由变化
      onPush: (url) => {
        if (pushState) {
          pushState(null, '', url)
        }
      },
      onReplace: (url) => {
        if (replaceState) {
          replaceState(null, '', url)
        }
      },
      // 其他方法...
    }
  }

  return createHistory()
}

关键点：

通过 # 段实现路由切换，无需服务器配置
路由变化通过 hashchange 事件监听

七、进阶使用

1. 动态切换路由模式的场景

在某些项目中，可能需要根据用户设备或网络环境动态切换路由模式。例如：

// 判断是否支持 HTML5 历史模式
const isHistoryModeSupported = 
  window.history && 
  window.history.pushState && 
  window.history.replaceState

const history = isHistoryModeSupported 
  ? createWebHistory() 
  : createWebHashHistory()

2. 处理历史记录的管理

在 HTML5 历史模式中，需要手动管理浏览器历史记录。例如：

router.beforeEach((to, from, next) => {
  // 手动管理历史记录
  history.pushState(null, '', to.fullPath)
  next()
})

3. SEO 优化策略

HTML5 模式：需要服务器配置为处理 / 路径的静态资源
哈希模式：无需配置，但 SEO 效果不如 HTML5 模式

八、性能与工程实践

1. 性能对比

项目	HTML5 模式	哈希模式
URL 美观性	✅ 高	❌ 低（包含 `#`）
刷新兼容性	❌ 需服务器配置	✅ 无需配置
SEO 优化	✅ 高	❌ 低
兼容性	❌ 不支持 IE11	✅ 兼容性好
历史记录管理	✅ 需要手动管理	❌ 无需管理

2. 性能优化建议

缓存路由组件：使用 import() 动态加载组件，避免一次性加载所有代码
懒加载路由：通过 component: () => import('./views/About.vue') 实现按需加载
预加载资源：使用 preload 指令提前加载常用路由的资源

3. 安全风险

HTML5 模式：可能存在 XSS 攻击风险（URL 中的参数可被恶意篡改）
哈希模式：虽然 URL 中的参数不直接暴露，但 # 后的内容仍可能被截取

九、常见问题与踩坑

1. 服务器配置错误（HTML5 模式）

问题描述：在 HTML5 模式下，刷新页面会出现 404 错误。

原因：服务器未正确配置，未将所有请求重定向到 index.html。

解决方案：

使用 Nginx 配置：

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

使用 Apache 配置：

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

2. 哈希模式下的 URL 美观性问题

问题描述：哈希模式下的 URL 显示为 #/about，显得不够专业。

解决方案：使用 createWebHistory 替换哈希模式，但需要服务器配置。

3. 历史记录管理错误（HTML5 模式）

问题描述：在 HTML5 模式下，手动管理历史记录时可能出现错误。

解决方案：使用 router.push 和 router.replace 方法代替直接调用 pushState。

十、最佳实践

1. 选择路由模式的建议

场景	推荐模式	理由
需要美观的 URL	HTML5 模式	适合现代 SPA 项目
需要兼容旧浏览器	哈希模式	兼容性好，无需服务器配置
项目需要 SEO 优化	HTML5 模式	搜索引擎更易抓取内容
项目需要动态管理历史记录	HTML5 模式	可通过 `router.push` 管理历史
项目需要快速开发	哈希模式	无需服务器配置，开发效率高

2. 推荐的代码组织方式

路由配置文件：将路由配置单独放在 router/index.js 中，便于维护
组件按需加载：使用 import() 动态加载组件，避免一次性加载所有代码
历史模式配置：在 main.js 中根据环境变量动态选择路由模式

十一、总结

Vue3 中的 createWebHistory 和 createWebHashHistory 是两种不同的路由模式，分别对应 HTML5 历史模式和哈希模式。它们的核心区别在于 URL 的更新机制和服务器配置要求。

HTML5 模式：适合现代 SPA 项目，URL 美观且 SEO 友好，但需要服务器配置
哈希模式：兼容性好，无需服务器配置，但 URL 不美观

在实际开发中，应根据项目需求选择合适的模式。对于需要美观 URL 和 SEO 优化的项目，推荐使用 HTML5 模式；对于需要快速开发或兼容旧浏览器的项目，推荐使用哈希模式。

开发人员应特别注意服务器配置问题，避免因配置错误导致页面无法访问。同时，要合理管理历史记录，确保应用的稳定性和可维护性。

通过深入理解这两种模式的原理和使用场景，可以更好地应对实际开发中的各种问题，提升开发效率和应用质量。

一、背景与问题

二、基本原理

1. HTML5 历史模式（createWebHistory）

2. 哈希模式（createWebHashHistory）

三、环境准备

1. 项目依赖

2. 开发环境

四、核心实现

1. 基础用法（代码示例）

示例 1：创建 HTML5 历史模式的路由

示例 2：创建哈希模式的路由

示例 3：动态切换路由模式

五、完整案例

1. 一个完整的 Vue3 应用（HTML5 模式）

项目结构

index.html

main.js

App.vue

router/index.js

views/Home.vue

views/About.vue

六、源码解析

1. createWebHistory 的实现原理

2. createWebHashHistory 的实现原理

七、进阶使用

1. 动态切换路由模式的场景

2. 处理历史记录的管理

3. SEO 优化策略

八、性能与工程实践

1. 性能对比

2. 性能优化建议

3. 安全风险

九、常见问题与踩坑

1. 服务器配置错误（HTML5 模式）

2. 哈希模式下的 URL 美观性问题

3. 历史记录管理错误（HTML5 模式）

十、最佳实践

1. 选择路由模式的建议

2. 推荐的代码组织方式

十一、总结

评论已关闭

推荐阅读

1. HTML5 历史模式（`createWebHistory`）

2. 哈希模式（`createWebHashHistory`）

`index.html`

`main.js`

`App.vue`

`router/index.js`

`views/Home.vue`

`views/About.vue`

1. `createWebHistory` 的实现原理

2. `createWebHashHistory` 的实现原理