Python多模块项目使用PyInstaller打包为EXE完整指南

一、背景与项目结构介绍

首次尝试将Python爬虫项目打包为EXE文件时，发现网上多数教程仅适用于单一py文件的简单Demo，对复杂项目帮助有限。

首先查看项目层级结构。本项目使用PyCharm创建，并配置了独立的虚拟Python解释器，以避免多项目环境冲突。项目划分为多个Python包：core包（包含项目入口py模块）、docs包（存放txt等非代码资源文件）、logs包、test包以及utils包。各模块独立开发，存在跨包import依赖关系，程序入口为core包下的spider_main.py。

二、实施步骤

1、总体思路

整个打包过程主要涉及两个核心命令。

（1）使用pyi-makespec -w xxx.py命令

首先执行pyi-makespec -w xxx.py命令，生成项目入口模块的spec文件。随后需对该spec文件进行自定义编辑，指定所需的资源。这类似于购房装修：家具和电视代表源代码，锅碗瓢盆代表txt文档、png图片等非代码资源文件，而入口代码模块则是房子的钥匙。PyInstaller作为“物业中介”交付样板房（即生成的spec文件），其中已预设客厅、厨房、卧室等格局（配置单元）。我们需要根据项目执行需求，决定在每个“房间”中放置何种内容。

pyi-makespec -w xxx.py

（2）使用pyinstaller -D xxx.spec命令

执行pyinstaller -D xxx.spec命令，利用定义好的spec文件（即装修计划），生成完整的EXE程序（完成房屋装修）。

pyinstaller -D xxx.spec

2、安装PyInstaller

由于使用虚拟Python解释器，需在项目虚拟环境中安装PyInstaller。在PyCharm底部Terminal中输入命令pip install pyinstaller进行安装。

pip install pyinstaller

3、具体步骤（以本项目为例）

（1）生成Spec文件并填充内容

执行以下命令：

pyi-makespec -w C:\Users\admin\PycharmProjects\spider\xiechengcar3\venv\Include\xiechengcar_spider\core\spider_main.py

（直接使用入口模块的绝对路径）

pyi-makespec -w C:\Users\admin\PycharmProjects\spider\xiechengcar3\venv\Include\xiechengcar_spider\spider_main.py

首先查看新生成的spec文件需要补充哪些内容，具体功能模块说明见下文。

接着查看补充完整后的spec文件内容，可结合项目层级结构进行参考。

以下是各配置单元的具体作用说明。

a) Py文件打包配置

针对包含多目录和多文件的Python项目，打包时需将所有相关py文件输入到Analysis类中。Analysis类中的pathex定义了打包的主目录，位于该目录下的py文件在配置时只需写文件名而无需写完整路径。

b) 资源文件打包配置

资源文件包括项目运行所需的相关文件，如图标文件、文本文件等。对此类资源文件的打包需设置Analysis的datas参数。

c) Hidden Import配置

PyInstaller在打包时会解析Python文件并自动寻找源文件的依赖模块。但解析过程中可能会遗漏某些模块（not visible to the analysis phase），导致打包后执行时出现“No Module named xxx”错误。此时需在Analysis下的hiddenimports中添加遗漏的模块。

（2）开始“装修”（打包EXE）

通过第二个命令pyinstaller -D xxx.spec（直接提供生成的spec文件的绝对路径，spec文件生成在Terminal打开的根目录下）将项目打包为EXE安装包。

pyinstaller -D C:\Users\admin\PycharmProjects\spider\xiechengcar3\spider_main.spec

（3）验证EXE文件

（a）查看生成的内容

进入执行命令的根目录，会发现新增两个文件夹：build和dist。

build为临时文件目录，记录打包过程中的错误信息（如warn-xx.txt），若遇到问题可查阅此文件；dist中存放打包结果，包括可执行文件及其他程序运行所需的关联文件。

根目录内容如下：

build目录内容如下：

dist目录内容如下：

(b) 运行EXE文件（方法1：直接双击EXE文件；方法2：在CMD中cd至当前目录，输入spider_main.exe运行）

三、疑难杂症及注意事项

1、打包时找不到模块问题

进入Terminal后，务必cd进入项目顶层目录（例如C:\Users\admin\PycharmProjects\spider\xiechengcar3）。切勿进入如C:\Users\admin\PycharmProjects\spider\xiechengcar3\venv\Include\xiechengcar_spider等子目录执行命令。必须在顶层目录执行，否则PyInstaller无法找到目录下的lib包及其他包的依赖。若依赖模块不全，无论怎样填充spec文件的datas列表，均会报No Module错误，导致打包失败。

2、打包成功但运行提示Failed to execute script

若打包过程无报错，但运行EXE时提示“execute fail”，并查看build的warn.txt文档显示各种missing model信息，请勿在此钻牛角尖。此时应首先检查打包路径是否为项目顶层目录，能否加载lib中的其他依赖模块；其次编辑spec文件，将exe单元下的console属性改为True（默认为False）并保存，然后重新执行第二个命令打包。重新打包后，在CMD下运行EXE文件，此时会显示具体错误原因（若不改此字段，无论双击还是CMD运行，均只会弹出无具体信息的Failed to execute错误）。根据提示解决是缺少依赖模块还是代码中无法读取非代码资源（txt、png等）的问题。若无法读取非代码资源，需根据提示的not found路径，手动建立相关目录并放入所需文档资源。

3、CMD下运行打包好的EXE，运行一段时间卡住不动，需按回车才继续

原因：在CMD快速编辑模式下，无意点击文字会选中文字，自动进入标记模式并暂停程序，需按任意键才能继续运行。

解决方法：

（1）非查错时避免使用CMD，建议直接双击EXE文件执行

（2）取消CMD的文本编辑模式

CMD在运行Python程序时偶尔会暂停且不报错，按Enter键可继续。

根本原因在于快速编辑模式下，无意点击文字会选中文字，自动进入标记模式并暂停程序。

解决方法：

1. 在CMD标题栏右键

2. 取消快速编辑（取消后无法复制CMD中的文字）

4、其他注意事项

（1）程序打包EXE时，最好注释掉模块中的测试main函数

PyInstaller与Python不同，即使使用if __name__ == '__main__':标识，PyInstaller在导入模块时仍会将main下的内容全部编译。因此建议务必注释掉测试代码，否则若涉及路径引用，会引发各种File Not Found错误，令人困惑。无论其他模块是否调用，均需处理。

（2）使用Windows PowerShell运行EXE程序时，程序结束后会报File Not Found错误，但直接双击EXE或PyCharm运行则无此问题

这令人疑惑：为何最后要去C盘寻找该文件，且即使未写入任何数据，程序仍要求该文件存在。例如本例中，日志文件路径通过以下函数获取：

os.path.dirname(os.path.dirname(__file__)) + '/docs/ipool.log'

在PyCharm中，获取当前父目录并拼接为/docs，将日志写入父目录下的/docs/ipool.log中。打包成EXE时，该文件位于dist\spider_main\Include\xiechengcar_spider\docs 处。但在Windows PowerShell中，当前父目录默认为C://，因此程序试图寻找C://docs/ipool.log文件。具体为何在程序结束时抛出此路径错误尚不明确，如有知情网友欢迎解答。经测试三种方法：一是在所需目录放置该文件；二是直接双击EXE执行，程序运行结束后直接关闭，未报错；三是直接忽略，但不确定是否影响项目结果。

到此关于Python多模块项目使用PyInstaller打包发布为EXE的介绍结束，更多相关内容请搜索本站以往文章或继续浏览相关文章，希望大家以后多多支持本站！