前端Vue3项目打包 dist 相对路径下：history vs hash 路由完整对比

前置关键前提

打包后 index.html 使用相对路径（vite.config.ts / vue.config.js 配置 base: './'）：

• hash 模式：完全兼容，无需后端配合，本地直接打开 dist/index.html 也能正常运行

• history 模式：相对路径 + history 组合极易 404，必须后端配置重定向，本地双击打开 html 直接白屏 / 404

一、两种模式核心原理

1. Hash 模式（默认模式）

路由格式：shturl.cc/3WDN690VAs66

1. # 是浏览器锚点，不会发给服务端，HTTP 请求永远只请求 index.html；

2. 路由切换仅前端 JS 监听 hashchange 事件，无页面刷新；

3. 打包使用 base: './' 相对路径完全适配，静态资源、路由路径不会错乱。

2. History 模式（干净无 #）

路由格式：shturl.cc/9jgPIPS41A

1. 基于 HTML5 History API（pushState/replaceState），URL 无#；

2. 浏览器刷新页面时，会把完整 /home 路径发给后端服务器；

3. 若后端无特殊配置，服务器会去找 /home 对应的文件，dist 里不存在该文件，直接返回 404；

4. 搭配相对路径 ./ 时，刷新、子路由嵌套极易出现 CSS/JS 资源 404。

二、核心区别对照表

三、dist 相对路径场景下两种模式坑点

1. Hash 模式（推荐纯静态、无后端场景）

配置示例（Vite）

ts

// vite.config.ts
export default defineConfig({
  base: './', // 相对路径
})
// router/index.ts
const router = createRouter({
  history: createWebHashHistory(), // hash模式
  routes
})

优点：

• 本地直接打开 dist/index.html 就能预览；

• 部署到 Nginx、COS、OSS、GitHub Pages 等静态存储，零配置；

• 子路由、多层嵌套路由静态资源不会丢失。

2. History 模式 + base: './' 巨大坑

ts

// vite.config.ts
base: './'
// router
history: createWebHistory()

问题：

1. 首页 / 打开正常，刷新 /user 直接 404；

2. 访问 /user 页面时，浏览器请求资源路径变成 ./user/assets/xxx.js，路径错误，资源加载失败白屏；

解决方案（二选一）

方案 A：改用绝对路径部署（推荐 history 模式使用）

ts

base: '/' // 根路径，域名直接访问项目

然后 Nginx 配置重定向：

nginx

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

方案 B：子目录部署 history（比如域名下 /admin）

ts

base: '/admin/'
history: createWebHistory('/admin')

四、怎么选（dist 相对路径场景）

1. 纯静态部署、无运维后端、OSS/GitPages、本地双击预览

   → 选 Hash 模式，省心无 404，相对路径完全兼容

2. 正式官网、需要 SEO、后端可配合配置 Nginx

   → 放弃相对路径，使用 base: '/' + History 模式，后端配置重定向

3. 强制必须使用相对路径且想用 history

   不推荐，会频繁出现静态资源 404，维护成本极高

补充：vite /vue-cli 对应 API

Vue3 Vite

• hash：createWebHashHistory()

• history：createWebHistory(基础路径)

Vue2/Vue-CLI

• hash：mode: 'hash'

• history：mode: 'history'