[Vite - Vue 3] 部署至GitHub Pages后刷新页面出现页面未找到问题求助

我之前也碰到过一模一样的坑！本地开发完全正常，一部署到GitHub Pages就刷新报错，核心原因其实是GitHub Pages是静态文件托管服务，不支持Vue Router history模式的路由重写逻辑。

本地开发时，Vite的开发服务器会帮你拦截所有路由请求，返回根目录的index.html让Vue Router在客户端解析；但GitHub Pages的静态服务器只会严格按照URL路径找对应文件——比如你刷新/study/xxx时，服务器会去搜这个路径下的文件，找不到就直接返回404了。

下面给你两种实用的解决方案：

方案1：切换到Hash模式（最简单直接） #

把Vue Router的history模式改成hash模式，hash模式下URL会带#，服务器只会解析#前面的基础路径（也就是你配置的/study），后面的路由完全由Vue Router在客户端处理，完美适配静态托管场景。

修改你的routes.js代码：

import { createRouter, createWebHashHistory } from 'vue-router';
import Home from './views/Home.vue';
const routes = [
    {
        path: '/',
        name: 'Home',
        component: Home,
    }
];
export default function () {
    return createRouter({
        // 将createWebHistory替换为createWebHashHistory
        history: createWebHashHistory('/study'),
        routes,
    });
}

重新build部署后，刷新页面就不会再出现404了，唯一的小变化是URL会多一个#，比如https://yourusername.github.io/study/#/，对功能完全没影响。

方案2：保留History模式（需额外配置） #

如果你不想URL带#，可以通过配置404页面来兼容：

1. 在项目的public文件夹下新建404.html，内容完全复制index.html的代码
2. 部署后，当用户刷新非根路径时，GitHub Pages会返回这个404.html，Vue Router就能在客户端正确解析路由
3. 确保vite.config.js的base和Router的base保持一致（你现在的配置已经没问题）

不过这个方案偶尔会有页面加载时短暂显示404状态的小问题，所以更推荐方案1。

最后再核对两个关键点：

• 确认vite.config.js的base设置为你的GitHub Pages仓库名称（你这里是'study'，配置正确）
• 打包后的文件要上传到GitHub Pages对应的分支（通常是gh-pages分支）

内容的提问来源于stack exchange，提问作者Tai Pham