Python项目本地运行正常 部署Heroku报ModuleNotFoundError错误

触发ModuleNotFoundError: No module named 'collections.abc'; 'collections' is not a package错误，核心是两类问题：

• 项目自定义文件和Python标准库命名冲突：项目目录（尤其是根目录）下存在名为collections.py的自定义文件，Python导入模块时优先加载当前项目路径下的文件，直接覆盖了标准库collections模块；本地运行正常是因为本地启动时的工作目录不是项目根目录，Heroku部署时默认以项目根为工作目录启动，直接触发冲突。
• 运行环境版本不匹配：collections.abc是Python 3.3版本之后正式归入collections模块下的子模块，如果Heroku默认拉取的Python版本低于3.3，或者安装的第三方依赖版本过旧、适配的是更低版本Python的导入逻辑，也会触发该报错。

按顺序排查操作即可解决：

• 清理命名冲突：遍历项目所有目录，找到命名为collections.py的自定义文件，重命名为和标准库不冲突的名称（比如my_collections.py），同步修改代码中所有对应导入语句；删除项目中所有__pycache__缓存目录，避免旧编译缓存干扰运行。
• 锁定Heroku运行的Python版本：在项目根目录新建runtime.txt文件，写入你本地跑通代码时用的Python版本，格式参考python-3.10.12，注意版本号需要在Heroku官方支持的Python版本列表范围内，Heroku构建时会读取该文件拉取对应版本的运行环境，不会使用默认的低版本镜像。
• 对齐依赖版本：在本地用和runtime.txt一致的Python版本创建虚拟环境，重新安装所有项目依赖，跑通功能后执行pip freeze > requirements.txt，把所有依赖的版本号完全锁死，保证Heroku部署时安装的依赖和本地运行环境完全一致，避免依赖版本不兼容触发导入错误。
• 本地预验证：修改完成后，本地切到项目根目录，用和HerokuProcfile中完全一致的启动命令启动项目，确认根目录启动无报错后，再推送代码到Heroku触发重新部署。

特殊情况处理：如果上述操作做完还是报错，就检查项目依赖的第三方库源码，找是否存在高版本Python下需要从collections.abc导入、但库代码还在从collections直接导入的写法，直接升级对应第三方库到适配当前Python版本的最新版即可。

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