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的资料请关注脚本之家其它相关文章!

相关文章

  • vue.js打包项目后页面出现空白的解决办法

    vue.js打包项目后页面出现空白的解决办法

    这篇文章主要介绍了vue.js打包项目后页面出现空白的解决办法,小编觉得挺不错的,现在分享给大家,也给大家做个参考。一起跟随小编过来看看吧
    2021-11-11
  • Vue中比较流行且好用的组件使用示例

    Vue中比较流行且好用的组件使用示例

    这篇文章主要介绍了Vue中比较流行且好用的一些组件使用示例详解,有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步,早日升职加薪
    2023-08-08
  • Vue3播放m3u8视频的两种实现方式示例

    Vue3播放m3u8视频的两种实现方式示例

    这篇文章主要介绍了Vue3播放m3u8视频的两种实现方式,两种视频播放器组件分别是vue3-video-play和chimee-player,文中通过代码介绍的非常详细,需要的朋友可以参考下
    2025-01-01
  • vue实现选项卡小案例

    vue实现选项卡小案例

    这篇文章主要为大家详细介绍了vue实现选项卡小案例,文中示例代码介绍的非常详细,具有一定的参考价值,感兴趣的小伙伴们可以参考一下
    2022-04-04
  • vue百度地图实现自定义弹框样式

    vue百度地图实现自定义弹框样式

    这篇文章主要介绍了vue百度地图实现自定义弹框样式,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
    2024-03-03
  • vue3时间插件之Moment.js使用教程

    vue3时间插件之Moment.js使用教程

    这篇文章主要给大家介绍了关于vue3时间插件之Moment.js使用的相关资料,需要的朋友可以参考下
    2023-09-09
  • Vue中实现动态右键菜单的示例代码

    Vue中实现动态右键菜单的示例代码

    在前端开发中,实现自定义右键菜单能够为用户提供更多功能选项,本文就来介绍了Vue中实现动态右键菜单的示例代码,感兴趣的可以了解一下
    2024-11-11
  • Vue中mixins混入的介绍与使用详解

    Vue中mixins混入的介绍与使用详解

    如果我们在每个组件中去重复定义这些属性和方法会使得项目出现代码冗余并提高了维护难度,针对这种情况官方提供了Mixins特性,这时使用Vue mixins混入有很大好处,下面就介绍下Vue mixins混入使用方法,需要的朋友参考下吧
    2022-12-12
  • 解决Vue+Electron下Vuex的Dispatch没有效果问题

    解决Vue+Electron下Vuex的Dispatch没有效果问题

    这篇文章主要介绍了Vue+Electron下Vuex的Dispatch没有效果的解决方案 ,本文给大家介绍的非常详细,具有一定的参考借鉴价值,需要的朋友可以参考下
    2019-05-05
  • Vue实现二维码数组的全选与反选功能

    Vue实现二维码数组的全选与反选功能

    在开发Web应用程序时,表格数据的展示和操作是非常常见的需求之一,特别是在处理表格中的复选框选择时,我们经常需要实现全选、反选等功能,这篇文章将带你深入了解如何在Vue.js中实现对二维数组数据的全选和反选功能,需要的朋友可以参考下
    2024-09-09

最新评论