在当今的前端开发领域，Vue.js 凭借其高效、灵活和易用的特点，成为了众多开发者的首选框架，当将 Vue 项目部署到服务器后，有时会遇到刷新页面时出现 404 错误的情况，这给用户体验带来了极大的影响，本文将深入探讨 Vue 部署到服务器刷新路由问题的原因、解决方案以及相关的注意事项，帮助开发者更好地应对这一挑战。

一、问题原因剖析

（一）前端路由原理差异

Vue Router 提供了两种路由模式：hash 模式和 history 模式，在 hash 模式下，访问 URL 中会包含 # 字符，例如http://your_domain/#/path，这种模式通过监听浏览器的onhashchange 事件来处理路由变化，当 URL 中的 hash 值改变时，Vue Router 会根据相应的规则加载对应的组件，但不会向服务器发送请求获取新的页面内容，因此不存在刷新页面导致 404 的问题。

而 history 模式则利用了 HTML5 的 History API，包括pushState 和replaceState 方法以及popstate 事件来实现路由跳转，在这种模式下，URL 看起来更加简洁，没有 # 字符，例如http://your_domain/path，当用户直接刷新页面或者通过浏览器地址栏输入特定的 URL 进行访问时，浏览器会向服务器请求该 URL 对应的资源，由于这些 URL 实际上是由 Vue Router 在前端虚拟出来的，服务器上并不存在对应的真实文件路径，所以如果没有进行正确的服务器配置，就会返回 404 错误。

（二）服务器对 SPA 支持不足

单页应用（SPA）与传统的多页应用在请求处理方式上有很大的不同，传统的多页应用，每个 URL 都对应一个实际存在的服务器端文件或资源，服务器能够根据请求的 URL 准确地找到并返回相应的文件，但对于 SPA 无论用户访问哪个 URL，服务器都应该返回相同的index.html 文件，然后由前端的 JavaScript 代码来决定如何渲染页面和处理路由，大多数服务器默认的配置并没有针对这种 SPA 的特性进行处理，从而导致在刷新页面时无法正确响应请求。

二、解决方案详述

（一）Nginx 服务器配置

1、基本配置示例

- 打开 Nginx 配置文件（通常位于/etc/nginx/nginx.conf 或/etc/nginx/sites-available/default），在server 块中添加以下配置：

server {
    listen       80;
    server_name  your_domain_or_ip;
    root        /path/to/your/dist;
    index       index.html index.htm;
    location / {
        try_files $uri $uri/ /index.html;
    }
}

- 这里的root 指令指定了 Vue 项目构建后的静态文件所在的目录。try_files 指令的作用是按照顺序检查文件是否存在，首先尝试查找与请求的 URL 对应的文件或目录，如果找不到，则继续查找index.html 文件，这样，当用户刷新页面或访问一个不存在的 URL 时，Nginx 都会返回index.html 文件，然后由 Vue Router 来处理后续的路由逻辑。

2、子目录部署配置

- 如果将项目部署到了服务器的某个子目录下，例如/h5，则需要在 Nginx 配置中进行相应的调整：

server {
    listen       80;
    server_name  your_domain_or_ip;
    location /h5 {
        alias /path/to/your/dist;
        try_files $uri $uri/ /h5/index.html;
    }
}

- 这里使用了alias 指令来指定子目录的别名，使得请求/h5 开头的 URL 能够正确地映射到本地的/path/to/your/dist 目录。try_files 指令仍然按照之前的逻辑进行文件查找，确保在子目录下也能正确处理路由刷新问题。

3、使用@router 位置块优化配置（可选）

- 为了更清晰地组织 Nginx 配置，也可以使用@router 位置块来专门处理路由重写：

server {
    listen       80;
    server_name  your_domain_or_ip;
    root        /path/to/your/dist;
    index       index.html index.htm;
    location / {
        try_files $uri $uri/ @router;
    }
    location @router {
        rewrite ^.*$ /index.html last;
    }
}

- 这种方式将路由重写的规则单独放在@router 位置块中，使得主配置文件的结构更加清晰，易于维护和理解。

（二）Apache 服务器配置

1、基本配置示例

- 在 Apache 服务器的配置文件（通常是/etc/apache2/apache2.conf 或/etc/httpd/conf/httpd.conf）中，找到网站配置的部分，添加以下配置：

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

- 这段配置启用了 Apache 的mod_rewrite 模块，并设置了一系列的规则。RewriteRule ^index\.html$ - [L] 确保直接访问index.html 文件时不会被重写。RewriteCond 指令用于判断请求的文件或目录是否存在，如果不存在，则使用RewriteRule . /index.html [L] 将所有其他请求重写为指向index.html 文件，这样，当用户刷新页面或访问一个不存在的 URL 时，Apache 会将请求转发给index.html，由 Vue Router 来处理路由。

2、子目录部署配置

- 如果项目部署在子目录下，例如/h5，需要修改RewriteBase 和重写规则：

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

- 这里的RewriteBase 被设置为/h5/，以便正确地处理子目录下的请求路径，其他规则的含义与基本配置相同，只是作用范围限定在了/h5 子目录下。

（三）Express.js 服务器配置（Node.js 环境）

1、基本配置示例

- 如果你使用 Node.js 和 Express.js 作为后端服务器，可以在服务器代码中添加以下配置：

const express = require('express');
const path = require('path');
const app = express();
const port = process.env.PORT || 3000;
app.use(express.static(path.join(__dirname, 'dist')));
app.get('*', (req, res) => {
    res.sendFile(path.join(__dirname, 'dist', 'index.html'));
});
app.listen(port, () => {
    console.log(Server is running on port ${port});
});

- 这里首先使用express.static 中间件将dist 目录设置为静态文件服务的根目录，以便提供项目中的静态资源，通过app.get('*'...) 添加了一个通配符路由处理器，用于捕获所有未匹配到其他路由的请求，并将这些请求都重定向到index.html 文件，这样，无论用户访问什么 URL，Express.js 服务器都会返回index.html，由 Vue Router 来处理后续的路由逻辑。

2、子目录部署配置

- 如果项目部署在子目录下，例如/h5，需要在服务器代码中进行相应的修改：

const express = require('express');
const path = require('path');
const app = express();
const port = process.env.PORT || 3000;
const basePath = '/h5'; // 设置子目录路径
app.use(express