部署在GitHub Pages的TinaCMS/Next.js根路径首次访问404问题排查

核心诱因分析 #

• GitHub Pages不支持服务器端URL重写：GitHub Pages是纯静态文件托管服务，仅能根据请求路径直接返回对应静态文件，无法执行Next.js rewrites()这类服务器端路由规则。你配置的source: "/", destination: "/home"重写逻辑，在Next.js SSR环境下由服务器处理，但静态导出后，GitHub Pages无法识别该规则。
• 静态导出未生成根路径的index.html：通过next export生成静态站点时，Next.js不会为rewrites()中的source路径自动生成对应的静态文件（即根目录下的index.html），仅会在/home目录下生成首页的静态资源。首次访问/时，GitHub Pages找不到根目录的index.html，直接返回404错误页。
• 客户端路由绕开了服务器限制：点击“Return to home”链接后正常显示，是因为该链接使用Next.js客户端路由（next/link），路由逻辑在浏览器端执行：客户端会依据rewrites()规则，将/映射到/home的内容，此时URL保持为/但实际渲染的是/home的静态资源，无需经过GitHub Pages的服务器端处理。

本地Nginx正常的原因 #

本地用Nginx托管时，可通过配置try_files或rewrite规则，将根路径请求转发到/home/index.html，相当于在服务器端模拟了Next.js的重写逻辑，因此首次访问根路径能正常加载。

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