Vue 项目部署在子目录下：hash vs history 的真实区别

文章目录

一、先说结论
[二、hash 和 history 的 URL 本质区别](#二、hash 和 history 的 URL 本质区别)
[三、子目录 + hash：为什么几乎不会出问题？](#三、子目录 + hash：为什么几乎不会出问题？)
[四、子目录 + history：为什么容易翻车？](#四、子目录 + history：为什么容易翻车？)
[五、history 模式在子目录下必须做哪些配置？](#五、history 模式在子目录下必须做哪些配置？)
[六、hash vs history：子目录下的真实对比](#六、hash vs history：子目录下的真实对比)
[七、什么时候才应该用 history？](#七、什么时候才应该用 history？)
八、推荐配置（子目录）
九、总结

在 Vue 项目部署中， 子目录部署 是一个非常常见、但也非常容易踩坑的场景，例如：

复制代码

http://ip:port/wvp/

而不是默认的：

复制代码

http://ip:port/

这时，Vue Router 的 hash 模式 和 history 模式 在行为上会出现本质区别。

一、先说结论

在子目录（如 /wvp/）下部署 Vue 项目：

✅ hash 模式：稳定、省心，几乎不需要后端配合

⚠️ history 模式：必须配合后端 / Nginx，否则刷新必 404

如果是内部系统 / 后台管理系统 ，强烈推荐 hash 模式。

二、hash 和 history 的 URL 本质区别

1️⃣ hash 模式

text 复制代码

/wvp/#/dashboard

特点：

# 后面的内容 不会发送给服务器
属于浏览器行为
前端路由完全由 Vue 接管

2️⃣ history 模式

text 复制代码

/wvp/dashboard

特点：

完整路径会发送给服务器
服务器必须知道如何处理这个路径

三、子目录 + hash：为什么几乎不会出问题？

访问流程解析

当访问：

text 复制代码

http://ip:port/wvp/#/dashboard

浏览器与服务器的交互是：

复制代码

浏览器请求 → /wvp/
服务器返回 → index.html
Vue Router 解析 → #/dashboard

👉 服务器永远只看到 /wvp/

hash 模式的优势

刷新页面不会 404
浏览器直接访问任意路由都正常
后端 / Nginx 无需任何额外配置

📌 子目录部署下，hash 模式天生安全

四、子目录 + history：为什么容易翻车？

访问流程解析

访问：

text 复制代码

http://ip:port/wvp/dashboard

服务器接收到的是：

text 复制代码

/wvp/dashboard

如果服务器没有配置该路径：

复制代码

→ 找不到资源
→ 返回 404

❌ 页面刷新 404

❌ 浏览器直接访问 404

❌ 前进 / 后退偶发 404

五、history 模式在子目录下必须做哪些配置？

1️⃣ 前端配置（缺一不可）

js 复制代码

// vue.config.js
module.exports = {
  publicPath: '/wvp/'
}

js 复制代码

// router/index.js
const router = new VueRouter({
  mode: 'history',
  base: '/wvp/',
  routes
})

2️⃣ Nginx / 后端配置（核心）

Nginx 示例

nginx 复制代码

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

含义：

如果是静态资源 → 正常返回
如果不是 → 统一返回 index.html
由 Vue Router 接管路由

如果没有这一步会怎样？

复制代码

/wvp/dashboard → Nginx找文件 → 找不到 → 404

六、hash vs history：子目录下的真实对比

对比项	hash 模式	history 模式
子目录部署	✅ 非常稳	⚠️ 易翻车
是否依赖后端	❌ 不需要	✅ 必须
页面刷新	✅ 永不 404	❌ 不配就 404
URL 美观	❌ 有 #	✅ 干净
SEO	❌ 差	✅ 好
运维成本	⭐ 低	⭐⭐⭐ 高

七、什么时候才应该用 history？

对外网站
需要 SEO
需要分享干净 URL
后端 / Nginx 完全可控

否则：

子目录部署 + 内部系统 → hash 是最优解

八、推荐配置（子目录）

js 复制代码

// vue.config.js
module.exports = {
  publicPath: '/wvp/'
}

js 复制代码

// router/index.js
export default new VueRouter({
  mode: 'hash',
  base: '/wvp/',
  routes
})

✅ 不依赖后端

✅ 刷新不炸

✅ 部署简单

九、总结

hash 是"工程优先"
history 是"美观优先"

在子目录部署场景下，稳定永远比好看重要。