本文详解在 WSO2 Choreo 平台部署 Python 应用时，如何通过 Procfile 和 requirements.txt 自动安装依赖模块（如 gspread），解决因缺失包导致的 No module named xxx 运行时错误。
本文详解在 wso2 choreo 平台部署 python 应用时，如何通过 `procfile` 和 `requirements.txt` 自动安装依赖模块（如 `gspread`），解决因缺失包导致的 `no module named xxx` 运行时错误。
WSO2 Choreo 默认不会自动执行依赖安装——即使你已提供 requirements.txt 文件。Choreo 的构建流程会识别该文件，但运行阶段（runtime）并不会主动调用 pip install。因此，当你直接执行 python3 script.py 时，环境中尚未安装 gspread 等依赖，便会出现类似以下错误：
No module named gspread.__main__ 'gspread' is a package and cannot be directly executed
该错误本质是模块未安装（而非脚本调用方式错误），根本原因在于依赖未被加载到运行环境。
✅ 正确解决方案：通过 Procfile 显式声明安装与启动流程
你需要在项目根目录下创建一个名为 Procfile 的纯文本文件（无扩展名），并按如下格式定义启动命令：
web: pip3 install -r requirements.txt && python3 script.py
? 注意：web 是 Choreo 支持的标准进程类型（适用于 HTTP 服务或长期运行任务）。若你部署的是定时任务（Scheduled Task），也需使用 web 类型——Choreo 当前不支持 worker 或 clock 等其他 Procfile 进程类型。
立即学习“Python免费学习笔记（深入）”；
✅ 配套要求：确保 requirements.txt 格式规范
你的 requirements.txt 应采用标准 pip 格式，每行一个包（支持版本约束），例如：
gspread==6.1.2 oauth2client==4.1.3 requests==2.31.0
✅ 推荐使用 pip freeze > requirements.txt 在干净虚拟环境中生成，避免冗余包；
❌ 避免包含注释、空行或 --index-url 等非标准指令（Choreo 当前仅支持基础依赖解析）。
⚠️ 关键注意事项
- Procfile 必须位于项目根目录，且文件名严格为 Procfile（大小写敏感，无 .txt 后缀）；
- 安装命令 pip3 install -r requirements.txt 必须与 python3 script.py 在同一行、用 && 连接，确保安装成功后才执行主脚本；
- 不要使用 python -m gspread 等误用方式——gspread 是库，不是可执行模块；正确用法是在脚本中 import gspread；
- 若依赖含 C 扩展（如 cryptography），请确认其 wheel 兼容 manylinux2014_x86_64（Choreo 构建环境基准）；必要时指定 --only-binary=:all:；
- 首次部署时，Choreo 会缓存 pip install 结果；如更新 requirements.txt，建议在 Choreo 控制台触发「重建」（Rebuild）以清除旧层缓存。
✅ 验证是否生效
部署后，可在 Choreo 日志中观察到类似输出：
Installing collected packages: oauth2client, gspread, requests Successfully installed gspread-6.1.2 oauth2client-4.1.3 requests-2.31.0 Running script.py...
至此，你的 Python 脚本即可正常导入并使用 gspread 等第三方模块。
总结
在 WSO2 Choreo 中管理 Python 依赖的核心原则是：将依赖安装作为运行流程的一部分，而非构建阶段的隐式行为。通过 Procfile 显式编排 pip3 install + python3 启动链，既符合 Choreo 的运行模型，也保证了环境一致性与可复现性。这是当前最稳定、官方推荐的 Python 模块集成方式。
