Django应用部署Heroku遇模块找不到错误：库与包名不一致（本地正常）

我之前也踩过这个一模一样的坑！明明本地跑的毫无问题，requirements.txt也用pip freeze生成了，推到Heroku就突然报模块找不到，核心问题其实是Heroku的依赖缓存或者解析逻辑偶尔会抽风，尤其是遇到包名和导入模块名不一致的情况（比如这里安装用django-phonenumber-field，代码里导入用phonenumber_field）。下面是我亲测有效的几个解决步骤：

• 第一步：确认requirements.txt的准确性
  打开你的requirements.txt，确保里面有明确的django-phonenumber-field记录，最好带上具体版本号（比如django-phonenumber-field==7.1.0），避免自动安装最新版本带来的兼容问题。有时候pip freeze可能会生成格式不规范的内容，比如多余的空格或无效注释，尽量保持依赖项的简洁准确。

• 第二步：清除Heroku的依赖缓存
  Heroku会缓存之前安装过的依赖包，有时候旧缓存会导致新的依赖没有被正确安装。执行以下命令清除缓存：

  # 先安装heroku-repo插件（如果没装过的话）
  heroku plugins:install heroku-repo
  # 清除指定应用的缓存
  heroku repo:purge_cache -a 你的应用名称
  

  清除缓存后重新推送代码到Heroku，它会从头开始安装所有依赖，这一步大概率能解决模块找不到的问题。

• 第三步：本地模拟Heroku环境排查
  有时候问题出在requirements.txt本身，只是本地环境因为之前安装过依赖所以没暴露。你可以创建一个全新的虚拟环境，只安装requirements.txt里的包，然后启动Django服务：

  # 创建并激活虚拟环境
  python -m venv heroku-test-env
  # Windows系统激活
  heroku-test-env\Scripts\activate
  # Mac/Linux系统激活
  source heroku-test-env/bin/activate
  # 安装依赖
  pip install -r requirements.txt
  # 启动Django服务
  python manage.py runserver
  

  如果这个全新环境也报同样的错误，那说明requirements.txt里确实有问题（比如漏掉了依赖或版本不兼容）；如果没问题，那就是Heroku的缓存或部署环节的问题，回到第二步再试一次。

• 第四步：检查Procfile配置
  确保你的Procfile里的启动命令没有手动修改依赖安装逻辑，正确的Procfile应该类似这样：

  web: gunicorn your_project_name.wsgi --log-file -
  

  不要在Procfile里添加pip install之类的命令，Heroku会自动根据requirements.txt安装所有依赖。

其实这种包名和模块名不一致的情况在PyPI上很常见（比如django-rest-framework对应导入的rest_framework），Heroku的pip安装是根据requirements.txt里的包名来拉取的，只要包名正确就应该能装对，但缓存或者偶尔的依赖解析bug会导致安装失败，清除缓存是最直接有效的解决办法。

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