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;
    }

    # 其他已有配置...
}

五、IIS 上配置 history 模式路由支持

在 IIS 上配置 history 模式路由支持，需要以下步骤：

步骤操作
1安装 URL Rewrite 模块
2在项目目录下配置 web.config
3重启 IIS，部署前端构建产物
4测试刷新路由及子路径是否正常展示

1、安装 URL Rewrite 模块

  1. 打开浏览器，访问 IIS 官方模块下载页面：

    🔗 https://www.iis.net/downloads/microsoft/url-rewrite

  2. 下载并安装适用于你系统的版本。

  3. 安装完成后，重启 IIS：

    iisreset

2、为什么要安装 URL Rewrite 模块？

默认情况下，IIS 只会处理实际存在的文件路径，比如 /index.html、/static/js/app.js 等。而像 /about、/user/123 这些前端路由，IIS 会当作实际路径查找，如果找不到就返回 404。

为了解决这个问题，我们需要使用 URL Rewrite 模块，告诉 IIS：

“除了真实文件和目录，其他所有路径都交给 index.html 处理。”

URL Rewrite 模块正是 IIS 中实现这种逻辑的必要组件。如果没有安装，web.config 中的 <rewrite> 配置将无效，甚至引发服务器错误。

3、配置 web.config 文件支持 SPA history 模式

在前端项目构建完成后（如 npm run build），将生成的 dist 目录部署到 IIS 对应的站点目录中，并在该目录下创建（或修改）web.config 文件，添加如下内容：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="SPA Routing" stopProcessing="true">
          <match url=".*" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          </conditions>
          <action type="Rewrite" url="/index.html" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

说明：

  • 所有访问路径（如 /about、/dashboard）都会被重写为 /index.html
  • index.html 由前端框架接管路由解析

4、可选：自定义 404 页面（用于前端无法匹配时）

如果你希望在找不到页面时展示一个自定义的 404 页面，可以在 web.config 中添加：

<httpErrors errorMode="Custom" existingResponse="Replace">
  <remove statusCode="404" />
  <error statusCode="404" path="/404.html" responseMode="ExecuteURL" />
</httpErrors>

六、最佳实践建议

  1. 开发环境：可以使用任意模式，现代开发服务器会自动处理 History 模式。

  2. 生产环境：

    • 如果有服务器配置权限：优先使用 History 模式+合适的服务器配置

    • 如果没有服务器配置权限或简单静态托管：使用 Hash 模式避免问题

  3. SEO 要求：如果应用需要被搜索引擎索引，应使用 History 模式。

  4. 配置测试：部署后务必测试各个路由的直接访问和刷新功能。

总结

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

最后更新时间:
贡献者: 何风顺