引言

在 Vue3 項(xiàng)目開(kāi)發(fā)中，使用vue-router的 History 模式（無(wú) #號(hào)路由）能讓 URL 更簡(jiǎn)潔美觀，但部署后刷新非根路徑（如/xinlan、/hongyou）時(shí)，常會(huì)出現(xiàn) 404 錯(cuò)誤。本文結(jié)合實(shí)際項(xiàng)目場(chǎng)景，從原理分析到服務(wù)器配置，完整解決這一問(wèn)題。

一、問(wèn)題現(xiàn)象

以實(shí)際 Vue3 項(xiàng)目為例，路由配置使用createWebHistory（History 模式），訪問(wèn)以下路徑時(shí)：

• ? http://192.168.1.137:88/（根路徑）：正常訪問(wèn)，刷新無(wú)問(wèn)題
• ? http://192.168.1.137:88/xinlan（子路徑）：首次訪問(wèn)正常，刷新報(bào) 404 錯(cuò)誤
• ? http://192.168.1.137:88/#/xinlan（Hash 模式）：刷新正常，但 URL 帶 #號(hào)不美觀

二、問(wèn)題本質(zhì)：History 模式與服務(wù)器的路由沖突

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

表格

2. 核心原因

Vue3 的 History 模式是前端路由，但刷新時(shí)瀏覽器會(huì)把/xinlan當(dāng)成服務(wù)器物理路徑，而服務(wù)器上不存在該路徑對(duì)應(yīng)的文件，因此返回 404。

三、解決方案：保留 History 模式 + 服務(wù)器兜底配置

步驟 1：確認(rèn) Vue3 路由配置（無(wú)需修改）

先確保項(xiàng)目路由配置正確，以下是實(shí)際項(xiàng)目的路由代碼（已驗(yàn)證無(wú)語(yǔ)法錯(cuò)誤）：

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: '心藍(lán)查詢(xún)' }
  },
  {
    path: '/hongyou',
    name: 'hongyou',
    component: () => import('../views/hongyousearch.vue'),
    meta: { title: '紅郵查詢(xún)' }
  },
  {
    path: '/ip',
    name: 'ip',
    component: () => import('../views/ipgenerate.vue'),
    meta: { title: 'IP生成' }
  }
]

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

// 頁(yè)面標(biāo)題設(shè)置
router.beforeEach((to, from, next) => {
  document.title = to.meta.title || 'RentHub'
  next()
})

export default router

步驟 2：服務(wù)器配置（核心解決步驟）

核心思路：讓服務(wù)器將所有非靜態(tài)文件的請(qǐng)求，都重定向到 Vue 項(xiàng)目的index.html，由前端路由接管解析。

場(chǎng)景 1：Nginx 部署（最常用）

1. 找到 Nginx 配置文件（如nginx.conf或站點(diǎn)配置文件，路徑通常為/etc/nginx/nginx.conf、/etc/nginx/conf.d/default.conf（Linux）或conf/nginx.conf（Windows））。
2. 添加 / 修改以下配置：

server {
    listen 88; # 對(duì)應(yīng)項(xiàng)目訪問(wèn)端口
    server_name 192.168.1.137; # 服務(wù)器內(nèi)網(wǎng)/外網(wǎng)IP
    root /path/to/your/vue/dist; # 替換為Vue項(xiàng)目打包后的dist目錄絕對(duì)路徑
    index index.html; # 默認(rèn)首頁(yè)

    # 核心規(guī)則：解決History模式刷新404
    location / {
        try_files $uri $uri/ /index.html; # 優(yōu)先找靜態(tài)文件，找不到則返回index.html
    }

    # 可選：靜態(tài)資源緩存（優(yōu)化加載速度）
    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

場(chǎng)景 2：Node.js + Express 部署

如果項(xiàng)目通過(guò) Node.js 的 Express 框架部署，創(chuàng)建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模式兜底規(guī)則
app.get('*', (req, res) => {
  res.sendFile(path.join(distPath, 'index.html'));
});

// 監(jiān)聽(tīng)88端口
app.listen(88, '192.168.1.137', () => {
  console.log('Vue3項(xiàng)目運(yùn)行在 http://192.168.1.137:88');
});

啟動(dòng)服務(wù)：

node server.js

場(chǎng)景 3：Vue CLI 開(kāi)發(fā)環(huán)境（本地調(diào)試）

如果本地開(kāi)發(fā)時(shí)遇到該問(wèn)題，修改vue.config.js（無(wú)則新建）：

module.exports = {
  devServer: {
    port: 88,
    host: '192.168.1.137',
    historyApiFallback: true, // 開(kāi)啟History模式兜底
    allowedHosts: 'all' // 允許內(nèi)網(wǎng)訪問(wèn)
  }
};

四、驗(yàn)證效果

配置完成后，訪問(wèn)以下路徑并刷新，確認(rèn)無(wú) 404 錯(cuò)誤：

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

五、常見(jiàn)問(wèn)題排查

1. 配置后仍 404：
   • 檢查root路徑是否為 Vue 打包后dist目錄的絕對(duì)路徑；
   • 確認(rèn) Nginx 已重啟；
   • 檢查端口 88 是否被其他服務(wù)占用。
2. 靜態(tài)資源加載失敗：
   • 確認(rèn)try_files規(guī)則中包含$uri（優(yōu)先加載靜態(tài)文件）；
   • 檢查dist目錄下是否有對(duì)應(yīng)的 js/css 文件。

總結(jié)

1. Vue3 History 模式刷新 404 的核心是「前端路由被服務(wù)器當(dāng)成物理路徑」，需通過(guò)服務(wù)器配置兜底到index.html；
2. Nginx 部署時(shí)，核心配置是try_files $uri $uri/ /index.html;；
3. 開(kāi)發(fā)環(huán)境可通過(guò)vue.config.js的historyApiFallback: true快速解決；
4. 該方案既保留了無(wú) #號(hào)的美觀 URL，又保證了刷新功能正常，適合生產(chǎn)環(huán)境部署。

以上就是Vue3 History模式刷新404問(wèn)題的原因分析和解決方案的詳細(xì)內(nèi)容，更多關(guān)于Vue3 History模式刷新404的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！

最新評(píng)論