GitHub Pages部署问题：Flask项目仅显示README.md而非index.html

核心原因 #

GitHub Pages仅支持静态网站部署（即纯HTML/CSS/JS这类无需后端运行的文件），无法运行Flask这类依赖Python环境的动态Web项目。当前页面显示README.md的原因有两个：要么你指定的部署目录中找不到index.html，GitHub Pages会默认展示仓库的README；要么你的index.html是Flask的模板文件，GitHub Pages无法执行Flask的渲染逻辑，自然无法正常显示。

解决办法分两种情况 #

情况1：仅展示静态版index.html #

如果不需要Flask的动态功能，只想静态展示index.html：

• 调整GitHub Pages部署设置：进入仓库的Settings -> Pages，选择正确的主分支（比如main），部署目录选择存放index.html的路径（比如根目录/(root)，不要选/docs，除非你把文件放在该目录下）。
• 迁移静态文件：将Flask项目templates文件夹中的index.html复制到选中的部署目录下，提交代码后等待GitHub Pages重新部署。
• 强制刷新页面：部署完成后，按Ctrl+F5清除浏览器缓存，查看页面是否正常显示。

情况2：运行完整的Flask动态应用 #

如果需要使用Flask的表单提交、路由跳转等动态功能，必须更换到支持Python运行环境的云平台：

• 选择合适平台：推荐使用Render、Railway或Fly.io，这些平台都提供免费额度，足够支撑个人项目运行。
• 以Render为例的部署步骤：
  • 登录Render平台，绑定你的GitHub仓库。
  • 创建新的Web服务，选择目标仓库，设置运行环境为Python。
  • 配置启动命令：填写gunicorn app:app（假设你的Flask入口文件为app.py，其中的Flask实例名为app）。
  • 等待部署完成后，即可获得可访问的动态Flask应用地址。

额外排查点 #

• 确认仓库目录结构：检查index.html是否存在于GitHub Pages设置的部署目录中，不要仅存放在Flask的templates或static文件夹内。
• 清除浏览器缓存：部署更新后，浏览器可能缓存旧页面，尝试Ctrl+F5强制刷新。

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