Vue3项目部署GitHub Pages后页面加载失败、路由404问题咨询

你当前vue.config.js中的publicPath配置符合项目部署路径要求，不需要调整，两个问题的根因和修复方式如下：

问题1：站点无法正常加载Vue应用 #

核心原因是gh-pages分支的部署文件层级错误。
GitHub Pages默认读取部署分支根目录下的index.html作为站点入口，如果你直接上传了整个/dist文件夹到gh-pages分支，分支根目录下仅存在dist目录，入口文件实际位于dist/index.html路径，服务无法找到入口文件自然无法加载应用。
git subtree push --prefix dist origin gh-pages命令的作用是将本地dist文件夹内部的所有构建产物直接推送到gh-pages分支根目录，而非把dist文件夹本身上传到分支。
修复步骤：

• 清空gh-pages分支的现有内容
• 本地重新执行npm run build生成最新构建产物
• 重新执行subtree推送命令，推送完成后到仓库的gh-pages分支文件列表确认：根目录直接存在index.html、assets等构建文件，不存在嵌套的dist文件夹层级

问题2：根路径无法直接展示首页、页面刷新返回404 #

核心原因是Vue Router使用了history模式，而GitHub Pages静态服务不支持history路由的回退规则。
单页应用的history模式下，所有路由切换都是前端JS动态渲染完成的，不会向服务器请求对应路径的实体文件。但GitHub Pages作为无自定义配置的静态托管服务，没有配置「所有路径匹配不到的请求都回退到index.html交由前端路由处理」的规则：

• 点击页面内logo跳转时是纯前端路由切换，所以能正常到达首页
• 直接访问根路径、刷新任意内页时，服务器会按路径查找实体文件，找不到对应文件就直接返回404
  修复方式二选一即可：
• 方案1（推荐，零额外配置）：将路由模式改为hash模式
  修改路由配置文件，把引入的createWebHistory替换为createWebHashHistory，路由路径会自动携带#标识，所有路由跳转不会触发服务器的路径查找，完全适配GitHub Pages这类静态托管场景，示例配置：

  import { createRouter, createWebHashHistory } from 'vue-router'
  // 引入你的页面组件
  const routes = [
    // 原有路由配置保持不变
  ]
  const router = createRouter({
    history: createWebHashHistory(process.env.BASE_URL), // 替换原有createWebHistory配置
    routes
  })
  export default router
  

  修改完成后重新构建、推送产物到gh-pages分支即可生效。
• 方案2：保留history模式，添加404重定向逻辑
  如果不想使用带#的hash路由，可在项目public目录下新建404.html，内容与index.html完全一致，同时在index.html的head标签内添加路径重写脚本，将404请求的路径参数转回前端路由可识别的格式。该方案配置繁琐且兼容性一般，非特殊需求不推荐使用。

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