Flask 报错修复实战：send_file() got an unexpected keyword argument ‘etag‘
目录
Flask 报错修复实战：send_file() got an unexpected keyword argument 'etag'
问题分析
Flask 版本查看
解决方案
方法一：兼容旧版本，移除 etag 参数 ✅
方法二：升级 Flask（⚠️宝塔用户不推荐）
总结
Flask 报错修复实战：send_file() got an unexpected keyword argument 'etag'
在使用 Flask 或基于 Flask 构建的系统（如宝塔面板）时，有时我们会遇到一些版本兼容性问题。近期在调试宝塔面板插件时，我遇到了如下报错：
TypeError: send_file() got an unexpected keyword argument 'etag'
该报错发生在路径 /www/server/panel/BTPanel/__init__.py 的第 1759 行，堆栈信息如下：
Traceback (most recent call last):File "/www/server/panel/pyenv/lib/python3.7/site-packages/flask/app.py", line 1950, in full_dispatch_requestrv = self.dispatch_request()File "/www/server/panel/pyenv/lib/python3.7/site-packages/flask/app.py", line 1936, in dispatch_requestreturn self.view_functions[rule.endpoint](**req.view_args)File "/www/server/panel/BTPanel/__init__.py", line 1759, in send_faviconreturn send_file(s_file, conditional=True, etag=True)
TypeError: send_file() got an unexpected keyword argument 'etag'问题分析
这个错误提示表明，Flask 的 send_file() 函数不支持 etag 这个参数。这通常发生在 Flask 1.x 版本中。在 Flask 2.0 之后，send_file() 才引入了对 etag 的原生支持。
而宝塔面板自带的 Python 环境和 Flask 框架通常是较老版本，不支持新参数。
Flask 版本查看
为了验证这一点，可以使用以下命令查看当前 Flask 版本：
python -c "import flask; print(flask.__version__)"
在我的环境中输出为：
1.1.2
确认确实是 1.x 版本。
解决方案
方法一：兼容旧版本，移除 etag 参数 ✅
这是最直接、最安全的修复方式，特别适用于宝塔这种内置环境，避免升级带来其它依赖冲突。
在 /www/server/panel/BTPanel/__init__.py 文件中，找到如下代码（大约在第 1759 行）：
return send_file(s_file, conditional=True, etag=True)
修改为：
return send_file(s_file, conditional=True)
或者更加保守地去掉所有非必要参数：
return send_file(s_file)
方法二：升级 Flask（⚠️宝塔用户不推荐）
如果你是在自定义 Flask 项目中，可以选择升级 Flask：
pip install --upgrade flask
升级后，send_file 即可支持 etag 参数。但请注意，宝塔面板高度集成，升级可能导致其它插件或核心功能报错，因此不推荐在宝塔环境中升级 Flask。
总结
这个问题的根本原因在于 Flask 版本兼容性。老版本不支持 send_file(etag=...)，而新版本才引入了该特性。推荐的做法是在生产环境中采用保守兼容写法，避免直接修改核心依赖库或盲目升级。
最佳实践：在使用第三方库时，始终注意版本依赖和变更日志，避免因 API 差异导致运行时错误。
如你也在使用宝塔面板并遇到类似报错，希望这篇博客能帮你快速定位问题、规避风险。如果你想了解 Flask 不同版本的 API 差异和升级建议，也欢迎留言探讨。