如何解决GitHub Pages无法识别Flask项目文件的问题

问题描述 #

我的Flask项目在本地Visual Studio Code中按如下目录结构可正常运行：

your_project/
├── static/
│   ├── main.css
│   └── noscript.css
├── templates/
│   └── index.html
└── images/
    ├── image1.jpg
    ├── image2.png
    └── ...

但上传至GitHub后，GitHub Pages无法正确识别文件。曾尝试将index.html移出templates文件夹，但情况反而恶化；手动输入URL访问到index.html时，CSS样式也无法加载。试过通过GitHub Desktop和网页端上传项目，调试许久仍未解决。

仓库地址：https://github.com/ciripmav/tester.git
站点地址：https://ciripmav.github.io/Wouldr/

核心原因 #

GitHub Pages仅支持托管纯静态HTML/CSS/JS资源，无法解析Flask的后端逻辑、模板渲染等动态内容，直接上传Flask项目结构肯定无法正常运行。

具体修复步骤 #

1. 导出Flask页面为静态文件 #

本地运行Flask项目，在浏览器中打开目标页面后：

• 按Ctrl+S（Windows）或Cmd+S（Mac）保存页面，选择「网页，全部」格式，浏览器会自动把HTML、关联的CSS、图片等资源保存到本地文件夹。

2. 调整目录结构适配GitHub Pages #

GitHub Pages默认优先识别根目录下的index.html，整理后的仓库结构应该是：

your_repo/
├── index.html
├── static/
│   ├── main.css
│   └── noscript.css
└── images/
    ├── image1.jpg
    └── image2.png

3. 修正资源引用路径 #

打开导出的index.html，把所有动态路径替换为相对路径：

• 原Flask中的{{ url_for('static', filename='main.css') }}改为./static/main.css
• 图片路径改为./images/image1.jpg这类相对路径，确保和本地文件结构对应。

4. 重新上传并配置GitHub Pages #

• 将调整好的所有静态文件上传到GitHub仓库
• 进入仓库「Settings」→「Pages」，在「Source」选项中选择main分支和/root目录，保存后等待5-10分钟让站点生效。

避坑提示 #

• 不要上传Flask的templates文件夹和后端代码，GitHub Pages不会处理这些内容
• 避免使用绝对路径（如/static/main.css），优先用相对路径./static/main.css，防止路径跳转错误
• 若想使用docs文件夹托管，可将所有静态文件放入docs目录，然后在GitHub Pages设置中选择/docs目录。

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