Python Flask 运行出现 500 Internal Server Error 如何排查日志

Flask 出现 500 错误通常是因为应用代码抛出未捕获异常或服务器配置错误。排查时优先查看 Werkzeug 或 WSGI 服务器日志，生产环境严禁开启 debug 模式。

先说结论：Flask 500 错误本质是服务器内部异常，需通过日志定位 traceback，开发环境可开启 debug 显示详情，生产环境必须关闭 debug 并通过日志文件排查。

先确认：区分是 Flask 应用异常还是 Nginx/Gunicorn 配置错误
先处理：临时开启 debug 模式复现错误或直接查看服务器错误日志
再验证：修复代码后请求接口，确认状态码返回 200 且日志无报错

命令速用版

# 开发环境启动带调试信息
export FLASK_ENV=development
flask run

# 查看 Gunicorn 错误日志
tail -f /var/log/gunicorn/error.log

# 查看 Nginx 错误日志
tail -f /var/log/nginx/error.log

为什么会这样

500 Internal Server Error 表示服务器遇到了意料之外的情况，阻止了它完成请求。在 Flask 中，这通常意味着视图函数抛出了未捕获的 Python 异常，或者模板渲染失败，而错误处理机制未能捕获该异常。

默认生产模式下，Flask 为了安全会隐藏详细错误信息，只返回通用 500 页面，因此必须依赖日志系统记录 traceback 堆栈信息。

分步处理

步骤 1：开发环境复现

如果在本地开发，设置环境变量开启 debug 模式，浏览器会直接显示交互式调试控制台和堆栈信息。

export FLASK_DEBUG=1
python app.py

步骤 2：生产环境查日志

生产环境不能开启 debug，需检查 WSGI 服务器日志。如果使用 Gunicorn，默认 stderr 输出或配置了 accesslog/errorlog。

Python Flask 运行出现 500 Internal Server Error 如何排查日志

# 查找最近 500 错误对应的 traceback
grep "500" /var/log/gunicorn/error.log -C 5

步骤 3：配置 Python logging

确保 Flask 应用配置了 logging 模块，将异常记录到文件。

import logging
from logging.handlers import RotatingFileHandler

if not app.debug:
    file_handler = RotatingFileHandler('app.log', maxBytes=10240, backupCount=10)
    file_handler.setFormatter(logging.Formatter(
        '%(asctime)s %(levelname)s: %(message)s [in %(pathname)s:%(lineno)d]'))
    file_handler.setLevel(logging.INFO)
    app.logger.addHandler(file_handler)
    app.logger.setLevel(logging.INFO)
    app.logger.info('Microblog startup')

怎么验证是否生效

使用 curl 命令请求报错接口，观察 HTTP 状态码是否为 200，同时监控日志文件是否不再新增 ERROR 级别记录。

curl -I http://localhost:5000/problematic-route

检查日志文件中是否仍有 "Exception" 或 "Traceback" 关键字。

常见坑

生产环境开启 debug：允许用户执行任意代码，存在严重安全风险，必须确保 app.debug 为 False。
日志权限不足：Web 服务器用户无权写入日志文件，导致错误无法记录，需检查文件 ownership。
异常被吞掉：代码中存在裸 except 语句捕获了异常但未记录日志，导致排查困难。

常见问题

生产环境能开启 debug 模式排查吗？

不能。生产环境开启 debug 模式会让用户看到源代码和调试控制台，极易导致服务器被入侵，应通过日志系统排查。

Nginx 返回 500 和 Flask 返回 500 有什么区别？

Nginx 返回 500 通常是 Nginx 配置错误或上游服务器不可达，Flask 返回 500 是应用代码逻辑错误，需分别查看 Nginx error.log 和 Flask 应用日志。

数据库连接失败会导致 500 吗？

会。如果数据库连接异常未在代码中捕获处理，Flask 视图函数抛出异常后会直接返回 500 错误。

参考来源

Flask Official Documentation, Debug Mode, https://flask.palletsprojects.com/en/latest/quickstart/#debug-mode
Flask Official Documentation, Logging, https://flask.palletsprojects.com/en/latest/logging/