vue.js

关注公众号 jb51net

关闭
首页 > 网络编程 > JavaScript > javascript类库 > vue.js > Vue3 History模式刷新404

Vue3 History模式刷新404问题的原因分析和解决方案

作者：绝顶少年

在 Vue3 项目开发中,使用vue-router的 History 模式（无 #号路由）能让 URL 更简洁美观,但部署后刷新非根路径（如/xinlan、/hongyou）时,常会出现 404 错误,本文结合实际项目场景,从原理分析到服务器配置,完整解决这一问题,需要的朋友可以参考下

引言

在 Vue3 项目开发中，使用vue-router的 History 模式（无 #号路由）能让 URL 更简洁美观，但部署后刷新非根路径（如/xinlan、/hongyou）时，常会出现 404 错误。本文结合实际项目场景，从原理分析到服务器配置，完整解决这一问题。

一、问题现象

以实际 Vue3 项目为例，路由配置使用createWebHistory（History 模式），访问以下路径时：

二、问题本质：History 模式与服务器的路由冲突

1. Hash 模式 vs History 模式核心差异

表格

模式路由格式服务器请求路径刷新逻辑
Hash（createWebHashHistory）http://xxx/#/xinlan仅请求http://xxx/（根路径）服务器返回首页，前端解析 #后路由
History（createWebHistory）http://xxx/xinlan直接请求http://xxx/xinlan服务器查找/xinlan物理文件，找不到则 404

2. 核心原因

Vue3 的 History 模式是前端路由，但刷新时浏览器会把/xinlan当成服务器物理路径，而服务器上不存在该路径对应的文件，因此返回 404。

三、解决方案：保留 History 模式 + 服务器兜底配置

步骤 1：确认 Vue3 路由配置（无需修改）

先确保项目路由配置正确，以下是实际项目的路由代码（已验证无语法错误）：

import { createRouter, createWebHistory } from 'vue-router'

const routes = [
  {
    path: '/',
    name: 'home',
    component: () => import('../views/HomeView.vue'),
    meta: { title: '自用工具' }
  },
  {
    path: '/xinlan',
    name: 'xinlan',
    component: () => import('../views/xinlansearch.vue'),
    meta: { title: '心蓝查询' }
  },
  {
    path: '/hongyou',
    name: 'hongyou',
    component: () => import('../views/hongyousearch.vue'),
    meta: { title: '红邮查询' }
  },
  {
    path: '/ip',
    name: 'ip',
    component: () => import('../views/ipgenerate.vue'),
    meta: { title: 'IP生成' }
  }
]

const router = createRouter({
  history: createWebHistory(process.env.BASE_URL),
  routes
})

// 页面标题设置
router.beforeEach((to, from, next) => {
  document.title = to.meta.title || 'RentHub'
  next()
})

export default router

步骤 2：服务器配置（核心解决步骤）

核心思路：让服务器将所有非静态文件的请求，都重定向到 Vue 项目的index.html，由前端路由接管解析。

场景 1：Nginx 部署（最常用）

  1. 找到 Nginx 配置文件（如nginx.conf或站点配置文件，路径通常为/etc/nginx/nginx.conf、/etc/nginx/conf.d/default.conf（Linux）或conf/nginx.conf（Windows））。
  2. 添加 / 修改以下配置：
server {
    listen 88; # 对应项目访问端口
    server_name 192.168.1.137; # 服务器内网/外网IP
    root /path/to/your/vue/dist; # 替换为Vue项目打包后的dist目录绝对路径
    index index.html; # 默认首页

    # 核心规则：解决History模式刷新404
    location / {
        try_files $uri $uri/ /index.html; # 优先找静态文件，找不到则返回index.html
    }

    # 可选：静态资源缓存（优化加载速度）
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 7d; # 缓存7天
        add_header Cache-Control "public, max-age=604800";
    }
}

重启 Nginx 使配置生效：

# Windows

nginx -s reload

# Linux/Mac

sudo nginx -s reload

场景 2：Node.js + Express 部署

如果项目通过 Node.js 的 Express 框架部署，创建server.js文件：

const express = require('express');
const path = require('path');
const app = express();

// 指向Vue打包后的dist目录
const distPath = path.join(__dirname, 'dist');
app.use(express.static(distPath));

// History模式兜底规则
app.get('*', (req, res) => {
  res.sendFile(path.join(distPath, 'index.html'));
});

// 监听88端口
app.listen(88, '192.168.1.137', () => {
  console.log('Vue3项目运行在 http://192.168.1.137:88');
});

启动服务：

node server.js

场景 3：Vue CLI 开发环境（本地调试）

如果本地开发时遇到该问题，修改vue.config.js（无则新建）：

module.exports = {
  devServer: {
    port: 88,
    host: '192.168.1.137',
    historyApiFallback: true, // 开启History模式兜底
    allowedHosts: 'all' // 允许内网访问
  }
};

四、验证效果

配置完成后，访问以下路径并刷新，确认无 404 错误：

五、常见问题排查

  1. 配置后仍 404：
    • 检查root路径是否为 Vue 打包后dist目录的绝对路径；
    • 确认 Nginx 已重启；
    • 检查端口 88 是否被其他服务占用。
  2. 静态资源加载失败：
    • 确认try_files规则中包含$uri（优先加载静态文件）；
    • 检查dist目录下是否有对应的 js/css 文件。

总结

  1. Vue3 History 模式刷新 404 的核心是「前端路由被服务器当成物理路径」，需通过服务器配置兜底到index.html；
  2. Nginx 部署时，核心配置是try_files $uri $uri/ /index.html;；
  3. 开发环境可通过vue.config.js的historyApiFallback: true快速解决；
  4. 该方案既保留了无 #号的美观 URL，又保证了刷新功能正常，适合生产环境部署。

以上就是Vue3 History模式刷新404问题的原因分析和解决方案的详细内容，更多关于Vue3 History模式刷新404的资料请关注脚本之家其它相关文章！

您可能感兴趣的文章:
阅读全文