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

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

引言

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

一、问题现象

以实际 Vue3 项目为例,路由配置使用createWebHistory(History 模式),访问以下路径时:

  • http://192.168.1.137:88/(根路径):正常访问,刷新无问题
  • http://192.168.1.137:88/xinlan(子路径):首次访问正常,刷新报 404 错误
  • http://192.168.1.137:88/#/xinlan(Hash 模式):刷新正常,但 URL 带 #号不美观

二、问题本质: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 错误:

  • http://192.168.1.137:88/xinlan
  • http://192.168.1.137:88/hongyou
  • http://192.168.1.137:88/ip

五、常见问题排查

  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.jshistoryApiFallback: true快速解决;
  4. 该方案既保留了无 #号的美观 URL,又保证了刷新功能正常,适合生产环境部署。

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

相关文章

  • Vue3中的组合式 API示例详解

    Vue3中的组合式 API示例详解

    组合式 API 是一系列 API 的集合,使我们可以使用函数而不是声明选项的方式书写 Vue 组件,这篇文章主要介绍了什么是Vue3的组合式 API,需要的朋友可以参考下
    2022-06-06
  • avue实现自定义搜索栏及清空搜索事件的实践

    avue实现自定义搜索栏及清空搜索事件的实践

    本文主要介绍了avue实现自定义搜索栏及清空搜索事件的实践,主要包括对搜索栏进行自定义,并通过按钮实现折叠搜索栏效果,具有一定的参考价值,感兴趣的可以了解一下
    2021-12-12
  • 基于Vue实现拖拽效果

    基于Vue实现拖拽效果

    这篇文章主要介绍了基于Vue实现拖拽效果,文中给大家介绍了clientY pageY screenY layerY offsetY的区别讲解,需要的朋友可以参考下
    2018-04-04
  • elementUI自定义上传文件功能实现(前端后端超详细过程)

    elementUI自定义上传文件功能实现(前端后端超详细过程)

    自定义上传思路很简单,下面这篇文章主要给大家介绍了关于elementUI自定义上传文件功能实现(前端后端超详细过程)的相关资料,文中通过实例代码介绍的非常详细,需要的朋友可以参考下
    2022-11-11
  • vue表格(table)计算总计方式

    vue表格(table)计算总计方式

    这篇文章主要介绍了vue表格(table)计算总计方式,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教
    2022-07-07
  • Vue3中reactive变量重新赋值无法响应的3种处理方法

    Vue3中reactive变量重新赋值无法响应的3种处理方法

    这篇文章主要给大家介绍了关于Vue3中reactive变量重新赋值无法响应的3种处理方法,在Vue3中可以使用reactive函数将一个普通对象转换为响应式对象,需要的朋友可以参考下
    2023-08-08
  • webpack4+express+mongodb+vue实现增删改查的示例

    webpack4+express+mongodb+vue实现增删改查的示例

    这篇文章主要介绍了webpack4+express+mongodb+vue 实现增删改查的示例,小编觉得挺不错的,现在分享给大家,也给大家做个参考。一起跟随小编过来看看吧
    2018-11-11
  • Vue3使用vue-qrcode-reader实现扫码绑定设备功能(推荐)

    Vue3使用vue-qrcode-reader实现扫码绑定设备功能(推荐)

    本文介绍了在Vue3中使用vue-qrcode-reader版本5.5.7来实现移动端的扫码绑定设备功能,用户通过扫描二维码自动获取设备序列号,并填充到添加设备界面,完成设备绑定的全过程,包含ScanCode.vue和DeviceAdd.vue两个主要界面的实现方式
    2024-10-10
  • el-form-item prop属性动态绑定不生效问题及解决

    el-form-item prop属性动态绑定不生效问题及解决

    这篇文章主要介绍了el-form-item prop属性动态绑定不生效问题及解决方案,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教
    2022-07-07
  • vue.js移动端app实战1:初始配置详解

    vue.js移动端app实战1:初始配置详解

    这篇文章主要介绍了vue.js移动端app实战1:初始配置详解,具有一定的参考价值,感兴趣的小伙伴们可以参考一下
    2017-07-07

最新评论