通过Heroku部署Python应用时出现appdirs导入错误求助

问题分析 #

从部署日志可见，错误触发于构建阶段的setuptools初始化流程：from pkg_resources.extern import appdirs执行失败。核心原因是指定的setuptools 60.9.0与Heroku默认使用的Python 3.12环境不兼容——旧版本setuptools在Python 3.12中移除了pkg_resources.extern下的appdirs导入路径，同时requirements.txt中的部分依赖（如scipy<1.7.3）也和Python 3.12存在兼容性冲突。此外，Heroku的构建环境与运行环境相互独立，requirements.txt中的setuptools版本无法自动同步到构建依赖环境，导致构建时仍使用不兼容的版本。

可行解决方案 #

方案1：指定兼容的Python版本 #

Python 3.12对旧版依赖兼容性较差，建议降级至更稳定的Python 3.11：

• 在项目根目录创建runtime.txt文件，写入：

  python-3.11.9
  

• 保留requirements.txt中的setuptools==60.9.0和appdirs==1.4.4，重新执行部署。

方案2：升级setuptools到兼容Python 3.12的版本 #

若坚持使用Python 3.12，需将setuptools升级至支持该版本的版本（≥65.5.0）：

• 修改requirements.txt中的setuptools配置：

  setuptools>=65.5.0
  

• 删除appdirs==1.4.4（新版setuptools已无需依赖该外部导入，会自行处理相关逻辑）
• 同步升级其他不兼容依赖，比如将scipy<1.7.3替换为scipy>=1.10.0（兼容Python 3.12的版本），避免后续冲突。

方案3：强制构建阶段使用指定依赖 #

若上述方法无效，可通过单独文件指定构建阶段依赖：

• 创建requirements-build.txt文件，写入：

  setuptools>=65.5.0
  wheel
  

• 在项目根目录创建setup.cfg文件，添加以下内容，告知pip使用该构建依赖文件：

  [build-system]
  requires = -r requirements-build.txt
  build-backend = setuptools.build_meta
  

额外注意事项 #

• requirements.txt中pyaudio==0.2.11; sys_platform == 'win32'仅会在Windows环境安装，Heroku的Linux环境不会加载该依赖。若应用依赖音频功能，需确认Heroku环境是否支持，或替换为跨平台替代方案。
• 部署前可通过Docker模拟Heroku的Linux环境测试依赖安装，提前排查兼容性问题。

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