Win10下PyInstaller4.2打包Django3.1.5生成可执行文件失败求助

适配运行环境 #

• 操作系统：Win 10
• Python版本：3.7
• Django版本：3.1.5
• PyInstaller版本：4.2

原执行打包流程 #

1. 项目根目录执行命令生成默认spec配置：pyi-makespec -D manage.py
2. 执行打包命令生成可执行文件：pyinstaller manage.spec

已尝试操作无效原因 #

• 曾在Lib\site-packages\PyInstaller\hooks路径下新增自定义hook-django.contrib.py，内容为强制收集django.contrib下的所有子模块作为隐藏导入
• 曾在manage.spec文件中补充hiddenimports相关配置
  上述操作未生效的核心原因：collect_submodules('django.contrib')的逻辑会强制遍历加载全量contrib子模块，包含依赖GDAL的gis模块，放大了原生导入异常，无法跳过gis模块的加载流程

核心报错根因拆解 #

• 无效隐藏导入报错：提示django.db.backends.__pycache__.base not found
  该问题为PyInstaller 4.2版本的已知扫描bug，会误将Python缓存目录下的文件路径识别为需要加载的隐藏导入，属于无实际影响的无效提示。
• GDAL库缺失报错：所有django.contrib.gis.*模块导入失败，提示未找到对应GDAL动态库
  触发原因是PyInstaller内置的Django钩子会默认遍历加载django.contrib下的所有子模块，gis模块依赖独立安装的GDAL动态库，未配置环境时就会触发连续多层导入异常。
• 路径类型兼容报错：os.path.join执行时提示传入的BASE_DIR为WindowsPath类型
  触发原因是Django 3.x版本默认将BASE_DIR定义为pathlib.Path对象，3.7版本的Python os模块对WindowsPath类型的兼容存在缺陷，传入参数时会触发类型错误。
• 语法解析报错：钩子读取INSTALLED_APPS时触发SyntaxError: unexpected EOF while parsing
  该问题为前置异常导致的连锁反应：settings.py因兼容问题加载中断，钩子读取到的配置内容被截断，eval解析时自然会出现EOF语法错误，前置问题解决后该报错会自动消失。

针对性修复操作 #

• 调整模块加载规则，排除未使用的gis模块
  不需要在PyInstaller全局钩子目录下新增自定义配置，直接修改项目内的manage.spec文件，在excludes配置中加入django.contrib.gis，跳过gis模块的加载流程；如果项目确实需要使用GIS功能，提前安装对应版本的GDAL动态库，并在settings.py中通过GDAL_LIBRARY_PATH指定库的绝对路径。
• 修复settings.py的路径兼容问题
  将settings.py中的BASE_DIR定义转换为字符串格式：

  # 原默认定义
  # BASE_DIR = Path(__file__).resolve().parent.parent
  # 兼容修复后的定义
  BASE_DIR = str(Path(__file__).resolve().parent.parent)
  

  确保后续所有os.path.join调用传入的参数为字符串类型，避免触发WindowsPath类型兼容错误。
• 屏蔽无效缓存目录扫描
  在manage.spec的excludes配置中加入django.db.backends.__pycache__路径，跳过对Python缓存目录的模块扫描，消除无效报错提示。
• 精简隐藏导入配置
  不需要强制用全量收集的方式加载django.contrib模块，仅加载项目INSTALLED_APPS中实际用到的django.contrib子模块即可，减少不必要的模块加载触发的异常。

内容的提问来源于stack exchange，提问作者Jay-Z