Mac OS Big Sur下PyInstaller打包Python应用报PIL模块缺失错误

PyInstaller 5.0dev0为开发预览版本，在macOS Big Sur环境下对虚拟环境内安装的第三方包的自动扫描逻辑存在缺陷，无法正确识别已安装的Pillow依赖，导致打包产物缺失PIL模块，运行时触发导入错误。该问题属于平台特定的兼容bug，因此同样的配置在Windows环境下可正常完成打包运行，在Big Sur系统中则会触发模块缺失报错，表现为Dock图标闪退、直接运行可执行文件提示ModuleNotFoundError: No module named 'PIL'。

• 手动补全缺失的模块导入配置
  修改项目根目录下生成的.spec配置文件，在Analysis节点的hiddenimports参数中手动补充Pillow相关的导入模块：

  a = Analysis(['klusterbox.py'],
               pathex=['/Users/thomasweeks/klusterbox/kb_install'],
               binaries=[],
               datas=[],
               # 手动声明需要扫描的Pillow子模块
               hiddenimports=['PIL', 'PIL.Image', 'PIL.ImageTk'],
               hookspath=[],
               runtime_hooks=[],
               excludes=[],
               win_no_prefer_redirects=False,
               win_private_assemblies=False,
               cipher=block_cipher,
               noarchive=False)
  

• 替换存在兼容问题的PyInstaller版本
  5.0dev0属于开发预览版，在Big Sur环境下存在多处虚拟环境路径扫描bug，需替换为稳定版本：
  1. 在当前激活的虚拟环境中卸载现有开发版：
     pip uninstall pyinstaller
  2. 安装经过Big Sur兼容验证的稳定版本：
     pip install pyinstaller==4.10
• 排查虚拟环境路径错位问题
  执行打包前先运行校验命令，确认Python解释器的加载路径指向当前虚拟环境：
  python -c "import sys; print(sys.prefix)"
  若输出路径不包含当前虚拟环境的目录，说明虚拟环境激活状态失效，需重新激活后再执行打包流程，避免PyInstaller扫描到全局Python的包路径，漏掉虚拟环境内安装的Pillow。
• 调整打包参数适配最终需求
  若目标是生成无调试信息的单文件应用，将原打包命令中的-D（生成目录式包）替换为-F（生成单文件包），移除--log-level DEBUG调试参数，标准命令格式为：
  pyinstaller -w -F -i kb_sub/kb_images/kb_icon1.icns klusterbox.py

修改配置并重新打包完成后，不要直接双击.app启动验证，先在终端中运行dist目录下的对应可执行文件，确认无导入报错后，再双击启动.app，观察是否能正常进入运行界面。

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