通过GitHub Desktop推送仓库后GitHub页面访问返回404错误

问题背景 #

• 为完成课程作业在GitHub平台部署对应项目页面，所编写的算法在本地Eclipse IDE控制台运行所有JUnit测试无异常
• 本次仓库推送操作通过GitHub Desktop完成，本地运行测试全过，但教授及其他外部访问者访问项目GitHub页面时均返回404错误
• 项目仓库地址：Assignment7
• 暂无法定位故障原因，可落地的排查思路与解决方案整理如下

排查步骤与对应解决方案 #

• 检查Pages部署源配置
  进入仓库的Settings > Pages配置页，首先确认Source项是否正确选择了部署分支：普通静态站点要确认选中了存放网页文件的对应分支（通常是main/master分支），以及正确的文件目录（根目录/或是专门存放静态资源的/docs目录）。首次部署时很多人会保留Source默认的None选项，或是选错分支、选错目录，导致服务端找不到可部署的文件。如果是Maven/Gradle管理的Java项目，要确认是否配置了对应的GitHub Actions工作流，自动构建产出静态资源到部署目录——直接推送Java源码是无法被GitHub Pages直接识别渲染的。
• 检查入口文件与路径大小写
  GitHub Pages默认的站点入口文件是部署根目录下的index.html，如果入口文件命名错误（比如写成Index.html、home.html），或是放在深层子目录但没配置路径转发，服务端找不到入口就会直接返回404。注意GitHub服务端运行在Linux环境，严格区分路径和文件名大小写，而本地Windows、macOS系统默认不区分大小写，很容易出现本地能正常访问、线上路径匹配失败的问题，比如本地可正常加载的/Page/Home.html，如果仓库实际存储路径是/page/home.html就会触发404。
• 检查部署流程运行状态
  每次推送代码到部署分支后，GitHub需要1~3分钟完成构建和部署流程。进入仓库的Actions页面，查看对应Pages部署的工作流运行记录：如果出现红色的失败标记，点进详情查看具体报错日志，常见报错包括构建命令执行失败、单文件大小超限、Jekyll构建冲突。如果是纯静态非Jekyll项目，可以在部署根目录放一个命名为.nojekyll的空文件，跳过Jekyll默认构建流程，避免下划线开头的目录、特殊格式文件被Jekyll忽略导致的资源缺失问题。
• 检查仓库权限与自定义域名配置
  如果仓库是私有状态，未开通GitHub Pro的情况下无法启用公开可访问的Pages服务，先确认仓库可见性为Public。如果之前配置过自定义域名，检查域名解析是否生效、仓库根目录的CNAME文件内容是否和域名匹配。
• 核对GitHub Desktop推送记录
  打开GitHub Desktop对应仓库的提交历史，确认本地所有项目相关文件都已经完成commit并成功推送到远程对应分支，排查是否存在本地文件漏提交、提交后未推送导致远程仓库缺文件的问题。

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