Github Pages部署客户端路由SPA刷新非根路径返回404如何解决

你对问题的判断完全正确，Github Pages是纯静态文件服务器，没有服务端路由重写能力，无法像Express服务那样将所有路径请求都转发到index.html入口，所以直接访问非根路径会返回404。不需要为每个路由创建子目录，有两种成熟的方案可以解决这个问题：

方案一：404.html 回退方案 #

利用Github Pages的特性：当请求路径不存在时，会自动返回站点根目录下的404.html文件。你可以通过以下配置实现客户端路由正常运行：

1. 在项目静态资源根目录新建404.html，内容和index.html完全一致。这样所有不存在的路径请求都会返回你的SPA入口文件，客户端路由可以正常识别路径渲染对应页面。

注意：这个方案默认返回的HTTP状态码是404，如果需要优化SEO，可以在404.html中加入重定向脚本，将路径转为查询参数传递给index.html，再由客户端替换为干净的路由路径：

<!-- 加入到404.html的head标签最顶部 -->
<script>
const fullPath = location.pathname + location.search + location.hash;
location.replace(`/?path=${encodeURIComponent(fullPath)}`);
</script>

然后在index.html的路由初始化逻辑前加入路径还原代码：

document.addEventListener("DOMContentLoaded", () => {
  // 新增这段代码
  const query = new URLSearchParams(location.search);
  const redirectPath = query.get('path');
  if (redirectPath) {
    history.replaceState(null, null, redirectPath);
    query.delete('path');
  }

  // 原有逻辑不变
  document.body.addEventListener("click", e => {
      if (e.target.matches("[data-link]")) {
          e.preventDefault();
          navigateTo(e.target.href);
      }
  });
  router();
});

方案二：改用Hash模式路由 #

这个方案改造成本最低，兼容性最好，只需要修改你现有的路由逻辑，将路径匹配从pathname改为读取URL的hash部分即可，Github Pages不会处理#之后的内容，所有请求都会命中根路径的index.html：
修改后的核心代码示例：

// 修改路由跳转逻辑
const navigateTo = url => {
    location.hash = url;
};

// 修改路由匹配逻辑，读取hash值
const router = async () => {
    const routes = [
        { path: "/", view: Dashboard },
        { path: "/posts", view: Posts },
        { path: "/posts/:id", view: PostView },
        { path: "/settings", view: Settings }
    ];

    // 把原来的location.pathname替换为location.hash.slice(1)，hash为空时默认返回根路径
    const currentPath = location.hash.slice(1) || '/';
    const potentialMatches = routes.map(route => {
        return {
            route: route,
            result: currentPath.match(pathToRegex(route.path))
        };
    });

    // 原有逻辑不变
    let match = potentialMatches.find(potentialMatch => potentialMatch.result !== null);
    if (!match) {
        match = {
            route: routes[0],
            result: [currentPath]
        };
    }
    const view = new match.route.view(getParams(match));
    document.querySelector("#app").innerHTML = await view.getHtml();
};

// 把原来的popstate监听改为hashchange监听
window.addEventListener('hashchange', router);

这个方案唯一的缺点是URL中会带有#符号，如果对URL美观度要求不高可以优先选择。

另外你提到的Express服务端代码确实无法在Github Pages环境运行，Github Pages仅支持静态文件托管，不支持运行Node.js服务端程序，不需要考虑这类方案。

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