GitHub Pages仅能加载index.html 其余HTML与CSS文件无法运行如何解决

核心问题原因 #

• 大小写敏感差异：GitHub Pages 基于Linux环境运行，文件路径大小写严格匹配，本地Windows/macOS系统默认文件系统大小写不敏感，因此本地运行正常的路径，部署后可能因为大小写不一致出现404。比如代码中引用About.html但实际文件名为about.html、写了CSS/main.css但实际目录是css都会触发该问题。
• 绝对路径适配问题：如果你的代码中用了开头带/的根绝对路径（比如/pages/blog.html、/css/style.css），GitHub Pages 部署在仓库子路径（格式为用户名.github.io/仓库名）时，根路径/指向的是用户名.github.io而非你的仓库根目录，导致资源寻址错误。
• 部署配置错误：若仓库Pages设置中指定的部署分支、根目录和你实际提交代码的分支、文件存放目录不匹配，也会导致非首页资源无法加载。

解决步骤 #

• 统一所有文件名、路径引用的大小写，推荐全部使用小写命名，避免大小写匹配冲突
• 把所有页面跳转、资源引用的路径全部替换为相对路径：
  • index.html 引用css文件：写./css/xxx.css
  • 子目录（比如pages目录）下的html文件引用css：写../css/xxx.css，跳转回首页写../index.html
  • 禁止所有路径以/开头
• 进入仓库Settings → Pages栏，确认部署分支是你提交代码的分支（比如main），部署目录选择/(root)，配置修改后保存等待重新部署
• 修改提交后等待2-3分钟，清空浏览器缓存再访问测试即可

内容的提问来源于stack exchange，提问作者Shashi Kumar Singh