Vue Router 的两种历史模式及部署配置详解

一、Vue Router 的两种历史模式

Vue Router 提供了两种主要的历史模式：Hash 模式和 History 模式，它们分别通过createWebHashHistory和createWebHistory来创建。

1. Hash 模式 (createWebHashHistory)

import { createRouter, createWebHashHistory } from "vue-router";

const router = createRouter({
  history: createWebHashHistory(),
  routes: [...]
});

特点：

URL 格式：使用井号(#)，如 https://example.com/#/home
不需要特殊服务器配置，因为#后的内容不会发送到服务器
对搜索引擎不友好，#后内容通常不被索引
适用于简单部署环境或不关注 SEO 的应用

2. History 模式 (createWebHistory)

import { createRouter, createWebHistory } from "vue-router";

const router = createRouter({
  history: createWebHistory(),
  routes: [...]
});

特点：

URL 格式：使用正常路径，如 https://example.com/home
需要服务器配置支持，否则刷新页面会 404
对搜索引擎友好，路由可以被正常索引
适合生产环境、需要 SEO 友好的应用

二、History 模式下的刷新页面 404 问题

使用 History 模式时，当用户刷新页面或直接访问非根路径 URL（如/login、/profile等），服务器会尝试查找对应的文件。由于这些路径在服务器上实际不存在，服务器会返回 404 错误。

问题原因： 在单页应用中，这些路由实际上是由前端路由处理的，不是真实的服务器路径。当直接请求这些路径时，请求会发送到服务器，而服务器找不到对应资源。

三、解决方案——服务器配置

解决方案的核心是：将所有请求重定向到 index.html，让前端路由接管导航。

1. Nginx 配置

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

这是最常用的配置，指示 Nginx 尝试提供请求的文件，如果找不到则返回 index.html。

2. Docker + Nginx 配置

如果使用 Docker 部署，可以创建自定义的 nginx.conf：

server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;
    index index.html;

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

然后在 docker-compose.yml 中挂载：

version: "3"

services:
  web:
    image: nginx:latest
    ports:
      - "8000:80"
    volumes:
      - .:/usr/share/nginx/html
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
    restart: unless-stopped

3. Apache 配置

在项目根目录创建.htaccess文件：

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

4. Express (Node.js) 服务器

const express = require("express")
const path = require("path")
const app = express()

app.use(express.static(path.join(__dirname, "dist")))

// 处理所有路由
app.get("*", (req, res) => {
  res.sendFile(path.join(__dirname, "dist", "index.html"))
})

app.listen(8000)

四、宝塔面板 Nginx 配置

在宝塔面板中，不需要修改主配置文件，只需在站点配置文件中添加适当的 location 块：

步骤如下：

在宝塔面板中创建新站点，或修改已有站点配置
进入网站设置 -> 配置文件
在 server{}块内添加以下配置：

server
{
    # 其他已有配置...

    # 关键配置：处理前端路由
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 其他已有配置...
}

五、最佳实践建议

开发环境：可以使用任意模式，现代开发服务器会自动处理 History 模式。
生产环境：
- 如果有服务器配置权限：优先使用 History 模式+合适的服务器配置
- 如果没有服务器配置权限或简单静态托管：使用 Hash 模式避免问题
SEO 要求：如果应用需要被搜索引擎索引，应使用 History 模式。
配置测试：部署后务必测试各个路由的直接访问和刷新功能。

总结

Vue Router 的两种历史模式各有优缺点，History 模式提供了更干净的 URL，但需要额外的服务器配置。通过正确配置服务器，可以解决 History 模式下的刷新页面 404 问题，让单页应用体验更完善。根据项目需求和部署环境，选择合适的模式，并确保服务器配置正确，是构建可靠 Vue 应用的关键一步。