Vue Router部署至GitHub Pages后刷新页面出现404问题求助

问题现象 #

部署到GitHub Pages后，通过导航菜单跳转页面完全正常，但刷新子页面（如https://[username].github.io/[repo-name]/about）或直接输入子页面URL时会触发404错误，仅首页能正常访问；本地开发环境刷新页面无异常。

问题原因 #

你使用的createWebHistory（history模式）属于前端路由，依赖服务器的重定向配置。当刷新或直接访问子页面时，GitHub Pages的静态服务器会尝试寻找对应路径的物理文件（比如/about对应的about.html），但单页应用（SPA）只有一个index.html入口文件，服务器找不到对应文件就会返回404。

解决方案 #

方案1：添加404.html适配history模式 #

在项目的public目录下创建404.html，内容和index.html完全一致。当服务器返回404时，会加载这个404.html文件，此时Vue Router就能接管路由逻辑，正确渲染对应的子页面。

方案2：配置正确的路由base路径 #

GitHub Pages的项目部署在https://[username].github.io/[repo-name]/路径下，需要确保路由的base路径匹配仓库名称：

• 若使用Vue CLI，在vue.config.js中添加配置：

module.exports = {
  publicPath: '/[repo-name]/'
}

• 若使用Vite，在vite.config.js中添加配置：

export default defineConfig({
  base: '/[repo-name]/'
})

路由代码中createWebHistory(process.env.BASE_URL)会自动读取这个配置，确保路由跳转和访问的路径正确。

方案3：（可选）切换为Hash模式 #

如果不介意URL中带有#，可以将路由改为Hash模式，此时服务器只会处理index.html，路由由前端Hash值控制，不会出现404问题。修改路由代码：

// 替换createWebHistory为createWebHashHistory
import { createRouter, createWebHashHistory } from 'vue-router';

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

验证步骤 #

1. 按上述方案修改配置后，重新打包项目
2. 将打包后的dist目录内容推送到GitHub Pages对应的分支（通常为gh-pages）
3. 部署完成后，刷新子页面或直接访问子页面URL，验证是否正常加载

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