Heroku部署Flask API出现Preparing metadata (pyproject.toml)运行失败

架构老林

2026-8-26

问题场景

基于Python 3.9.2版本开发Flask API，本地运行正常，可返回预期数据
计划部署到Heroku平台开展测试
已尝试下调requirements.txt中配置的Numpy版本，报错仍未解决

核心报错信息

Preparing metadata (pyproject.toml): finished with status 'error'
         error: subprocess-exited-with-error
         
         × Preparing metadata (pyproject.toml) did not run successfully.
         │ exit code: 1
         ╰─> [123 lines of output]
             setup.py:461: UserWarning: Unrecognized setuptools command ('dist_info --egg-base /tmp/pip-modern-metadata-anq37ukt'), proceeding with generating Cython sources and expanding templates
               warnings.warn("Unrecognized setuptools command ('{}'), proceeding with ")
             setup.py:563: DeprecationWarning:
             
               `numpy.distutils` is deprecated since NumPy 1.23.0, as a result
               of the deprecation of `distutils` itself. It will be removed for
               Python >= 3.12. For older Python versions it will remain present.
               It is recommended to use `setuptools < 60.0` for those Python versions.

排查解决步骤

强制Heroku使用与本地一致的Python版本
Heroku构建时默认拉取当前可用的最新稳定版Python，不会自动匹配本地3.9.2版本。在项目根目录新建runtime.txt文件，写入内容python-3.9.2，确保构建环境和本地开发环境版本完全一致，从根源避免依赖版本不兼容问题。
锁定setuptools到兼容版本
报错信息已经明确给出兼容要求：Python 3.9等3.12以下版本使用旧版numpy时，需要setuptools版本低于60.0。直接在requirements.txt的最顶部添加固定版本配置：setuptools==59.6.0，该版本是59.x分支的最终稳定版，完全适配旧版numpy的构建逻辑，不会触发distutils相关的命令识别错误。
锁定numpy到适配Python 3.9的稳定版本
不要使用1.23.0及以上版本的numpy，直接在requirements.txt中配置numpy==1.22.4，该版本针对Python 3.9提供了预编译的wheel安装包，Heroku构建时不需要本地拉取源码编译，会直接安装预构建包，跳过pyproject.toml元数据生成的编译流程，从根本上规避当前报错。如果numpy是pandas、opencv-python等库的间接依赖，不需要额外配置numpy版本，只要保证setuptools和Python版本符合要求即可。
清理Heroku构建缓存后重试
完成上述配置修改后，先执行缓存清理操作，避免旧的错误构建缓存导致新配置不生效，相关命令如下：
```
heroku plugins:install heroku-builds
heroku builds:cache:purge -a 你的Heroku应用名称
```
清理完成后再重新推送代码触发构建即可。
额外注意：不要直接使用pip freeze > requirements.txt导出全量本地依赖，这种方式会把本地环境安装的无关编译工具、冗余依赖全部导出，容易触发不必要的源码编译流程，只保留项目实际引用到的依赖即可。

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