在Heroku部署Python FastAPI出现onnx安装失败报错如何解决

Heroku 默认 Python 构建环境未预装 onnx 源码编译所需的系统依赖，报错里提到的缺失 Protobuf 编译器（protoc）是直接失败诱因。当 pip 找不到和你当前 Python 版本、Heroku 运行栈匹配的 onnx 预编译 wheel 包时，会自动回退到源码编译模式，编译过程需要调用 CMake、Protobuf 编译器等系统工具，依赖缺失就会直接中断构建，最终导致代码推送被拒。

• 优先替换为无需编译的推理依赖
  绝大多数 FastAPI 部署 ONNX 模型的场景只需要做推理，不需要全量 onnx 包的模型构建、编辑能力。直接把requirements.txt里的onnx替换为onnxruntime即可，这个包提供全平台的预编译wheel，安装过程不需要编译系统依赖，体积更小、安装速度更快，不会触发当前的报错。
• 锁定有预编译wheel的onnx版本
  如果确实需要使用全量onnx包，不要在requirements.txt里写无版本约束的onnx，先确认Heroku当前使用的Python版本，选择对应版本已经发布预编译wheel的onnx版本号写入依赖文件，让pip直接下载预编译包，跳过源码编译环节。
• 补充系统依赖构建流程
  如果必须从源码编译onnx，先给应用添加apt构建包，在项目根目录执行命令：

  heroku buildpacks:add --index 1 heroku-community/apt
  

  之后在项目根目录新建名为Aptfile的文件，写入编译所需的系统依赖：

  cmake
  protobuf-compiler
  libprotobuf-dev
  

  该构建包会在Python依赖安装前自动读取Aptfile安装对应系统组件，解决Protobuf编译器找不到的问题。
• 清空缓存重新部署
  配置完成后先清除Heroku的历史构建缓存，避免之前失败的编译缓存影响结果，执行以下命令后重新推送代码即可：

  heroku plugins:install heroku-builds
  heroku builds:cache:purge
  git push heroku main
  

避坑提示：不要随意锁定过低版本的onnx，低版本onnx对新版Python、新版Heroku运行栈的兼容性很差，基本没有对应预编译包，会强制触发源码编译流程提高部署失败概率。

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