将带应用的Django微服务改造为可安装包时出现应用导入报错

核心报错根因 #

出现Cannot import 'polls'的报错，和你在INSTALLED_APPS里写的AppConfig路径没有关系，本质是Django加载PollsConfig类时，读取的类内部name属性值错误，导致Django找错了应用的实际位置。
Django的应用加载逻辑为：

1. 解析INSTALLED_APPS中的配置项，如果是指向AppConfig类的字符串，先导入对应的AppConfig类
2. 读取该类的name属性作为应用模块的实际导入路径
3. 尝试导入该路径下的模块，导入失败就抛出当前遇到的报错

• 优先检查mysite/polls/apps.py中PollsConfig类的name属性配置
  按照Django默认生成的应用代码，这个属性的初始值是name = "polls"，这种写法在本地直接运行项目时（mysite为项目根下的顶级目录）没有问题，但当mysite被打包为带命名空间的独立安装包后，这种短路径写法会让Django尝试从顶级Python路径查找名为polls的模块，完全无法匹配嵌套在mysite内部的polls应用。
  正确的配置需要写完整的模块导入路径：

  class PollsConfig(AppConfig):
      default_auto_field = 'django.db.models.BigAutoField'
      name = 'mysite.polls'  # 替换原有短路径配置
  

打包流程的常见遗漏问题 #

• 确认setuptools能正确识别所有需要打包的Python包
  当前setup.py中配置了package_dir={"": "src"}、packages=setuptools.find_packages(where="src")，这种写法要求所有需要打包的目录下必须存在__init__.py文件（哪怕是空文件），否则find_packages不会将这些目录识别为可安装的Python模块。
  可以在本地src目录下执行如下命令做验证：

  python -c "import setuptools; print(setuptools.find_packages('.'))"
  

  正常输出需要包含mysite、mysite.polls两个条目，如果出现缺失，需要在对应目录下补创建空的__init__.py文件，再重新执行打包流程。
• 验证安装后的模块导入链路
  完成包安装后，先在Python交互环境下逐环节测试导入逻辑，定位具体断点：

  # 第一步：验证mysite包本身安装正常
  import mysite
  print(mysite.__file__)
  
  # 第二步：验证polls应用可以被导入
  import mysite.polls
  
  # 第三步：验证AppConfig的路径配置正确
  from mysite.polls.apps import PollsConfig
  print(PollsConfig.name)
  

  对应排查方向：
  • 第一步导入失败：说明包的packages配置遗漏了mysite模块，重新检查打包文件列表
  • 第二步导入失败：说明mysite/polls目录未被正确打包，补__init__.py后重新打包
  • 第三步输出的name值为'polls'而非'mysite.polls'，即之前提到的AppConfig配置错误

补充注意事项 #

• 应用路径的配置要和模块的实际嵌套层级保持一致，只要应用是嵌套在mysite包下的，无论开发环境还是打包安装环境，统一用完整的模块路径做配置即可。
• 检查settings.py中的BASE_DIR配置，确认路径是基于mysite包的实际安装路径生成的，避免沿用本地开发时的绝对路径导致模板、静态文件加载失败。

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