使用href、src加载页面和图片出错 GitHub Pages报404本地运行正常

核心原因 #

本地开发环境和GitHub Pages的静态资源解析规则存在差异，常见触发原因如下：

• 路径根目录偏移：如果你的GitHub Pages部署在仓库子路径下（例如仓库名为my-site，访问地址为https://<用户名>.github.io/my-site/），此时路径开头的/对应的是github.io根目录而非你的仓库根目录，本地live server默认以项目文件夹为根目录，就会出现本地正常、部署后路径不匹配的问题。
• 大小写敏感差异：GitHub Pages使用的Linux文件系统大小写敏感，而Windows、macOS默认大小写不敏感。例如你本地文件名为About.html，代码里写about.html本地可以正常访问，部署后就会返回404。
• 后缀自动补全规则差异：多数本地开发服务（包括live server）默认会自动补全.html等静态资源后缀，你写href="pages/sub-pages/page"会自动匹配到page.html，但GitHub Pages默认不会做自动补全，路径不完整就会触发404。
• 目录结构不匹配：你描述中创建的文件夹名为sub-pages，但跳转路径写的是pages/sub-pages/page，需要确认你本地项目根目录下是否存在外层pages文件夹，部分本地服务的路径重写规则会掩盖目录结构不匹配的问题，部署后就会暴露。

可直接落地的修复步骤 #

• 先核对GitHub仓库的部署分支（通常为gh-pages或main分支）的文件结构，确认sub-pages文件夹的存放位置、内部文件的名称、后缀、大小写和你代码里写的路径完全一致。
• 修正路径写法：
  • 如果站点部署在仓库子路径下，避免使用开头带/的绝对路径，改用相对当前文件的相对路径，或者统一添加仓库名前缀，例如仓库名为my-blog，就写为href="/my-blog/pages/sub-pages/page.html"
  • 补全完整的文件后缀，把href="pages/sub-pages/page"改为href="pages/sub-pages/page.html"（根据实际文件后缀调整）
• 本地验证时关闭自动补全：可以使用npx serve命令在项目根目录启动静态服务，替代live server测试路径兼容性，提前发现问题。
• 如果你使用的是Vue、React等单页应用框架且开启了history路由模式，需要额外添加404 fallback配置，把所有路由请求都指向根目录的index.html即可。

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