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

杨影说影

目录

• 一、先说结论
• 二、hash 和 history 的 URL 本质区别
• 三、子目录 + hash：为什么几乎不会出问题？
• 四、子目录 + history：为什么容易翻车？
• 五、history 模式在子目录下必须做哪些配置？
• 六、hash vs 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 模式

/wvp/#/dashboard

特点：

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

2️⃣ history 模式

/wvp/dashboard

特点：

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

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

访问流程解析

当访问：

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

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

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

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

hash 模式的优势

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

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

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

访问流程解析

访问：

http://ip:port/wvp/dashboard

服务器接收到的是：

/wvp/dashboard

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

→ 找不到资源
→ 返回 404

❌ 页面刷新 404
❌ 浏览器直接访问 404
❌ 前进 / 后退偶发 404

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

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

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

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

2️⃣ 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 是最优解

八、推荐配置（子目录）

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

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

✅ 不依赖后端
✅ 刷新不炸
✅ 部署简单

九、总结

hash 是“工程优先”
history 是“美观优先”

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