部署在GitHub Pages的Vue网站刷新时出现404问题排查

你遇到的刷新404问题，核心是Vue Router的history模式和GitHub Pages的静态托管机制不兼容。

当你开启mode: 'history'时，Vue Router会把URL处理成/posts这类看起来像真实服务器路径的格式，但GitHub Pages是纯静态文件服务器——它只会响应实际存在的文件请求。比如你刷新/posts时，服务器会去寻找/posts这个文件或目录，而你的项目里只有index.html这一个入口文件，服务器找不到对应资源，自然就返回404了。

而平时从首页点击导航跳转时，是Vue Router在前端直接处理路由切换，不会向服务器发请求，所以不会出问题。

解决步骤 #

要让GitHub Pages支持history模式的路由刷新，关键是让服务器在遇到不存在的路径时，仍然加载你的Vue应用入口（index.html），再让Vue Router接管路由处理。具体操作如下：

1. 创建自定义404.html文件

在项目的public目录（或根目录，取决于你的Vue版本）新建一个404.html，内容和index.html完全一致。构建后这个文件会被同步到docs目录（对应你的build配置）。

GitHub Pages有个特性：当请求的路径不存在时，会自动加载404.html。这样刷新时服务器返回的404.html和index.html一样，能正常加载你的Vue应用。

2. 添加路由修复脚本

在index.html和404.html的<head>标签里，加入一段处理URL的脚本：

<script>
  (function() {
    const path = window.location.pathname;
    // 排除静态资源路径，只处理路由路径
    if (path !== '/' && !path.startsWith('/static/')) {
      // 把当前路径转成hash格式，让Vue Router能识别
      window.history.replaceState(null, null, '/#' + path);
      // 刷新页面让Vue应用加载对应路由
      window.location.reload();
    }
  })();
</script>

这段脚本会在页面加载时，把非根路径的URL转成hash格式（比如/posts变成/#/posts），Vue Router就能正确解析并渲染对应的组件了。

3. 验证路由配置（可选）

你的现有路由配置没问题，但可以明确指定base参数确保兼容性：

export default new Router({
  mode: 'history',
  base: '/', // 个人站点根路径，默认就是'/'
  routes: [
    { path: '/', name: 'Home', component: Home },
    { path: '/work', name: 'Work', component: Work },
    { path: '/posts', name: 'Posts', component: Posts },
    { path: '*', component: Home }
  ]
})

4. 重新构建部署

运行npm run build重新构建项目，再把docs目录的内容推送到christopherkade.github.io的master分支即可。

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