Gunicorn 启动时返回 404 是因应用实例未在模块顶层完成初始化，导致路由未注册；关键在于将 create_app() 调用移出 if __name__ == '__main__': 块，确保 WSGI 服务器能加载完整配置与路由。
gunicorn 启动时返回 404 是因应用实例未在模块顶层完成初始化，导致路由未注册；关键在于将 `create_app()` 调用移出 `if __name__ == '__main__':` 块，确保 wsgi 服务器能加载完整配置与路由。
在使用 Gunicorn 部署 Flask 应用时，一个常见但隐蔽的错误是：应用对象（app）未在模块顶层被完全初始化。你观察到 python app.py 可正常访问而 gunicorn app:app 返回 404，这并非端口或静态文件路径问题，而是 Gunicorn 加载机制与 Flask 应用工厂模式不匹配 所致。
Gunicorn 通过 app:app 导入语法直接从模块中获取可调用的 WSGI 实例（即 app 变量）。它不会执行 if __name__ == '__main__': 下的代码块，因此若 create_app() 仅在此条件内调用（如原代码中），则 app 在模块导入时仍为一个空的、未配置的 Flask(__name__, static_folder='ui') 实例——此时所有装饰器（如 @app.route）虽已注册，但 CORS(app) 和配置加载均未执行，更严重的是：@app.route 绑定依赖于 app 的实际状态，而工厂函数未运行意味着中间件、蓝图、甚至部分路由逻辑可能失效。
✅ 正确做法是：将 app = create_app(...) 提升至模块顶层，确保 Gunicorn 导入时即获得一个完全初始化的、路由就绪的应用实例：
创建 Flask + Vue.js 全栈项目，采用单端口架构、uv 依赖管理、结构化日志和生产级前端设计。当用户要求以下操作时触发：创建新的 Flask+Vue 项目、搭建 Web 应用、构建全栈 Python+Vue 应用、初始化 Flask Web 项目、设置单端口 Flask 前后端项目。触发词：新建项目、创建项目、搭建项目、Flask项目、Vue项目。
# app.py
from flask import Flask, send_from_directory
from flask_cors import CORS
import os
# 1. 基础实例（仅占位，不直接使用）
app = Flask(__name__, static_folder='ui')
# 2. 应用工厂函数（定义配置与扩展）
def create_app(config_name='default'):
"""Application factory function"""
# 注意：此处应重新创建 app 实例，而非复用顶层变量（见下方说明）
app = Flask(__name__, static_folder='ui')
CORS(app)
# 假设 config 已正确定义，例如：
# from config import config
# app.config.from_object(config[config_name])
return app
# ✅ 关键修复：在模块顶层调用工厂函数，生成最终 WSGI 实例
app = create_app(os.getenv('FLASK_CONFIG', 'default'))
# 3. 路由定义（必须在 app 初始化之后！）
@app.route('/', defaults={'path': ''})
@app.route('/<path:path>')
def index(path):
if path and os.path.exists(os.path.join(app.static_folder, path)):
return send_from_directory(app.static_folder, path)
else:
return send_from_directory(app.static_folder, 'index.html')
# 4. 仅用于开发：python app.py 启动
if __name__ == '__main__':
app.run()⚠️ 注意事项：
-
避免复用未初始化的顶层
app：原代码中app = Flask(...)后又在create_app()中操作同一对象，易引发状态混乱。推荐在工厂函数内新建app实例并返回（如上所示），这是 Flask 官方推荐的工厂模式实践。 -
静态路径健壮性：使用
os.path.join(app.static_folder, path)替代字符串拼接，防止路径遍历或跨平台问题。 -
调试建议：启动 Gunicorn 时添加
--log-level debug --capture-output，并检查access.log确认请求是否抵达、响应码是否为 404（而非连接失败）。 -
生产环境补充：建议配合
gunicorn.conf.py管理配置，并设置--chdir指向项目根目录，确保static_folder相对路径解析正确。
总结：Gunicorn 的 WSGI 加载机制要求应用对象必须在模块导入阶段即处于“就绪”状态。将应用初始化逻辑移出 if __name__ == '__main__': 是解决此类 404 的根本方法——这不是 bug，而是 WSGI 服务器与 Python 模块加载机制协同工作的必然要求。
