使用GitHub发布网站失败仅显示README文件如何解决

按以下优先级从高到低排查，绝大多数场景都能定位问题：

• 核对部署源配置
  进入仓库的Settings > Pages页面，确认Source模块选中的分支、部署目录和你实际存放站点文件的位置匹配：文件直接放仓库根目录就选/(root)，文件存放在docs目录才选/docs；如果用GitHub Actions自定义工作流部署，要确认工作流配置里上传的部署产物路径是完整的站点文件目录，不是只含README的仓库根路径。
• 检查首页入口文件命名
  GitHub Pages默认识别的站点首页入口是全小写命名的index.html，命名为Index.html、home.html等都不会被识别为首页。缺少合规的index.html时，Pages会默认渲染根目录的README.md作为首页，这是该问题最常见的诱因。
• 排查路径大小写问题
  GitHub Pages的服务端是大小写敏感的，本地Windows/macOS开发时系统默认大小写不敏感，不会暴露路径写错的问题——比如代码里引用资源写的是/JS/App.js，实际文件路径是/js/app.js，部署后就会404加载失败，把所有引用路径和实际文件名的大小写完全对齐即可。
• 确认部署分支的文件完整性
  检查Pages配置选中的部署分支（一般是main/gh-pages）里有没有完整上传所有站点文件，很多人会误把站点文件提交到dev等开发分支，部署分支里只有README文件，自然无法加载其他内容，把站点文件合并/推送到正确的部署分支即可。
• 验证构建流程是否正常
  如果是React/Vue/Angular等前端框架项目，要确认部署的是执行构建命令（一般是npm run build）后生成的产物目录（通常是dist、build文件夹），不要直接上传源码目录；用Actions部署的话，去仓库Actions tab查看对应部署工作流的运行日志，确认构建步骤没有报错、成功生成了完整的站点产物。
• 处理Jekyll编译冲突
  GitHub Pages默认会调用Jekyll处理仓库内的文件，非Jekyll构建的站点如果存在以下划线开头的文件/文件夹，会被Jekyll默认忽略导致资源丢失。在仓库根目录新建一个命名为.nojekyll的空文件提交，即可跳过Jekyll编译流程。
• 等待部署生效并清缓存
  每次提交触发部署后，Pages的生效时间从几十秒到数分钟不等，可以在Settings > Pages页面查看部署状态，显示站点已上线后，按Ctrl+F5硬刷新浏览器清缓存再访问，避免本地缓存导致看到旧的README页面。

额外注意：如果配置了自定义域名，要确认DNS解析配置正确、CNAME文件存放在站点根目录，解析未生效时也可能出现页面加载异常。

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