GitHub Pages部署异常求助：仅显示README内容或返回404错误

前置配置核对 #

所有操作都在GitHub对应仓库的网页版完成，不需要用到Git命令：

• 根目录必须存在index.html文件：这是站点的首页文件，没有的话GitHub Pages默认会展示README.md内容，这是你第一个仓库仅显示README的核心原因
• 私有仓库公开站点权限设置：进入仓库「Settings」→ 侧边栏选择「Pages」→ 找到「GitHub Pages visibility」选项，选择「Public」（该功能仅GitHub Pro订阅用户可用）
• 部署源设置：同一Pages设置页的「Source」区域，选择你存放站点文件的分支（默认一般为main），分支后的目录选项选择「/root（根目录）」，点击保存即可

第一个仓库（仅展示README内容）修复步骤 #

• 删除你之前加在README里的permalink配置，该配置是Jekyll静态站点专用，普通纯静态站点不需要
• 把你做好的站点首页文件重命名为index.html，放到仓库根目录，所有关联的css、js、图片等资源一起放到根目录，注意资源路径要写相对路径（比如./style.css，不要写本地磁盘路径）
• 提交修改后等待3-5分钟，刷新站点即可正常展示

第二个仓库（访问返回404）修复步骤 #

• 个人主页类型的站点，仓库名必须严格符合你的GitHub用户名.github.io规则，大小写、字符完全一致，比如用户名为test123，仓库名必须是test123.github.io
• 重复上文「前置配置核对」的所有步骤，确认配置没有错误
• 拉到Pages设置页最下方，查看「Deployments」板块的部署记录，如果有红色失败标识，点击即可查看具体报错原因，最常见的问题是根目录未检测到index.html

通用注意事项 #

• GitHub Pages部署存在3-5分钟延迟，每次修改提交后不要立刻刷新页面，等待几分钟再访问
• 访问时可以按Ctrl+F5强制刷新清除本地缓存，或者用浏览器隐身窗口访问，避免缓存旧页面导致显示异常

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