简介PyInstaller 安装包面向需要将 Python 脚本打包为独立可执行文件的开发者尤其适合希望把项目分发给未安装 Python 环境用户的初中级工程师。资源以源码包形式提供共 19 个文件包含 10 个 txt 说明与测试文本、5 个 py 脚本、2 个 pkg-info 元数据、1 个 cfg 配置及 1 个 regen-docs 文档生成脚本压缩包约 37KB体积轻量便于快速查阅。该版本围绕依赖分析、静态链接、多平台支持与输出格式定制等核心能力组织代码并附带基础测试用例与文档目录可帮助读者理解打包工具的内部实现与配置方式。目前已有 588 人学习下载适合作为研究 Python 打包机制、排查动态库依赖与资源文件处理问题的参考素材。1. 从一次打包翻车说起pyinstaller 安装包到底怎么装才不折腾上周帮一个做桌面工具的朋友排查问题他的 Python 脚本在本地跑得好好的用 PyInstaller 打成 exe 之后换台机器就闪退连报错窗口都看不到。折腾了一下午才发现问题根本不在打包参数上而是他装 PyInstaller 的方式就不对——直接pip install pyinstaller装到了全局环境结果打包时混进了一堆无关依赖体积飙到 300 多 MB还带着一堆用不上的动态库。这个场景太常见了PyInstaller 本身安装不复杂但装错环境、装错版本、装完不验证后面打包出来的东西就是黑匣子出了问题只能靠猜。这篇笔记就把 PyInstaller 安装包这件事从头到尾捋一遍从环境隔离、版本选择、依赖补齐到装完怎么验证、坏了怎么救适合刚接触打包的新手也适合被环境问题坑过的老手。2. 装之前先把环境理清楚Python 版本、虚拟环境和依赖边界2.1 Python 版本怎么选别踩 3.12 的坑PyInstaller 对 Python 版本是有脾气 的。截至我写这篇笔记的时候PyInstaller 6.x 系列已经能比较稳定地支持 Python 3.8 到 3.12但如果你用的是 Python 3.13 或者更早的 3.7就得留个心眼。我一般会先确认当前解释器版本python --version # 或者 python3 --version如果输出是Python 3.11.x或3.12.x基本可以放心往下走。如果是 3.13建议先查一下 PyInstaller 官方 release note 里有没有明确写支持没有的话就退到 3.12 或者 3.11。为什么强调这个因为 PyInstaller 打包时要读取 Python 的字节码和动态库版本差一个小版本内部结构可能就变了打包出来的 exe 在目标机器上可能直接报ImportError或者Failed to execute script。我自己的习惯是打包用的 Python 版本尽量和目标机器上运行环境保持一致如果目标机器不确定就选一个 LTS 性质的版本比如 3.11兼容性最稳。2.2 虚拟环境不是可选项是必选项很多人图省事直接全局pip install pyinstaller然后打包。这么做不是不行但后患无穷。全局环境里装了几十个包PyInstaller 分析依赖时会把它们全扫一遍哪怕你的脚本只用了requests和tkinter它也可能把numpy、pandas的二进制文件一起塞进去最后 exe 体积爆炸启动还慢。更麻烦的是如果全局环境里某个包版本和你的脚本不兼容打包出来的东西在别人机器上跑不起来你连排查方向都没有。所以第一步先建虚拟环境。用venv就行不需要额外装东西# 在项目根目录下创建虚拟环境 python -m venv .venv # Windows 激活 .venv\Scripts\activate # macOS / Linux 激活 source .venv/bin/activate激活之后命令行前面会出现(.venv)提示。这时候再装 PyInstaller它就只在这个隔离环境里生效不会污染全局。我一般还会在项目根目录放一个requirements.txt把脚本真正依赖的包写进去比如requests2.31.0 pillow10.2.0然后pip install -r requirements.txt再装 PyInstaller。这样打包时 PyInstaller 扫描到的依赖就是干净的体积和兼容性都可控。2.3 依赖边界哪些包需要额外处理有些包 PyInstaller 不能自动识别比如用了动态导入、C 扩展、或者运行时才加载资源的库。常见的有pandas、numpy、PyQt5、opencv-python这些。装完 PyInstaller 之后如果打包报错说找不到某个模块大概率就是这类包没被正确收集。解决办法是在打包命令里加--hidden-import或者--collect-all这个后面章节会细说。但装的时候就要有意识先把脚本依赖装全再装 PyInstaller顺序反了容易漏。3. 安装 PyInstallerpip 直装、版本锁定和离线包处理3.1 标准安装流程与版本选择环境激活之后安装命令本身很简单pip install pyinstaller但我不建议直接这么装因为默认会拉最新版而最新版有时候和你的 Python 小版本有兼容问题。我一般会指定一个经过验证的版本比如pip install pyinstaller6.3.0为什么是 6.3.0这个版本对 Python 3.11 和 3.12 支持都比较稳而且修复了之前 5.x 里一些--onefile模式下的路径问题。如果你不确定用哪个版本可以先pip index versions pyinstaller看看有哪些版本然后选一个 release 时间在半年以上、没有严重 bug 报告的。装完之后验证一下pyinstaller --version # 输出类似 6.3.0如果提示command not found说明虚拟环境的 Scripts 目录没在 PATH 里或者你忘了激活环境。Windows 下可以试试python -m PyInstaller --version这个方式不依赖 PATH更稳。3.2 离线安装和国内源加速有些公司内网机器不能直连外网或者下载速度慢得让人想砸键盘。这时候有两个办法一是用国内镜像源加速二是提前下载 whl 包离线安装。镜像源加速pip install pyinstaller6.3.0 -i https://pypi.tuna.tsinghua.edu.cn/simple这个命令里的-i参数指定了清华源下载速度会快很多。如果你所在网络对特定源有限制换成阿里云或腾讯云的源也行格式类似。离线安装的话先在能上网的机器上下载 whl 包和它的依赖pip download pyinstaller6.3.0 -d ./offline_pkgs然后把offline_pkgs目录拷到目标机器执行pip install --no-index --find-links./offline_pkgs pyinstaller6.3.0--no-index表示不走网络--find-links指定本地包目录。注意 PyInstaller 依赖pyinstaller-hooks-contrib、altgraph、pefileWindows等包pip download会一并下载别只拷一个主包。3.3 安装后的目录结构确认装完之后我习惯看一眼 PyInstaller 装到哪了以及它的 hooks 目录是否完整。因为很多打包报错都和 hooks 缺失有关。python -c import PyInstaller; print(PyInstaller.__file__)输出会指向虚拟环境下的site-packages/PyInstaller/__init__.py。同级目录下应该能看到hooks文件夹里面按模块名存放了各种 hook 脚本。如果这个文件夹是空的或者缺少你用的库对应的 hook打包时就会报ModuleNotFoundError。这时候可以手动装pyinstaller-hooks-contribpip install pyinstaller-hooks-contrib这个包是 PyInstaller 官方维护的额外 hooks 集合覆盖了很多第三方库装完能省不少事。4. 配置与打包参数从 spec 文件到 hidden-import 的取舍4.1 第一次打包用命令行快速验证装好之后别急着写复杂配置先用一个最简单的脚本跑通流程。假设你有个hello.py# hello.py import sys def main(): print(Hello from PyInstaller) input(Press Enter to exit...) if __name__ __main__: main()打包命令pyinstaller --onefile hello.py--onefile表示把所有东西打成一个 exe方便分发。执行完之后当前目录会出现dist和build两个文件夹dist里就是hello.exeWindows或hellomacOS/Linux。双击运行如果能看到输出说明基础环境没问题。这一步很关键先用最小脚本验证 PyInstaller 本身能跑通再去打真实项目否则出了问题你分不清是环境问题还是项目依赖问题。4.2 spec 文件参数多了就得靠它命令行参数一多敲起来容易漏而且不好版本管理。PyInstaller 支持把配置写进.spec文件。第一次打包时加--specpath或者直接让它生成pyinstaller --onefile --name myapp hello.py执行后目录下会多一个myapp.spec。这个文件本质是个 Python 脚本内容大概长这样# myapp.spec a Analysis( [hello.py], pathex[], binaries[], datas[], hiddenimports[], hookspath[], runtime_hooks[], excludes[], noarchiveFalse, ) pyz PYZ(a.pure) exe EXE( pyz, a.scripts, a.binaries, a.datas, [], namemyapp, debugFalse, bootloader_ignore_signalsFalse, stripFalse, upxTrue, consoleTrue, )关键参数说明hiddenimports用来手动指定 PyInstaller 没自动发现的模块datas用来打包非代码文件比如配置文件、图标、模型文件excludes用来排除明确不需要的包减小体积consoleTrue表示保留控制台窗口如果是 GUI 程序可以改成False。改完 spec 文件后用pyinstaller myapp.spec重新打包不用再敲一长串命令行参数。4.3 hidden-import 和 collect-all 怎么选遇到ModuleNotFoundError时优先试--hidden-importpyinstaller --onefile --hidden-importpkg_resources myapp.spec如果某个库有一堆子模块和资源文件一个个加 hidden-import 太累就用--collect-allpyinstaller --onefile --collect-all pandas myapp.spec--collect-all会把指定包的所有子模块、数据文件、动态库都收集进来。代价是体积会变大所以只对确实需要的包用。我一般会先试 hidden-import不行再上 collect-all最后再考虑在 spec 里手动写datas和binaries。5. 避坑与排查装完打不出包时先看这几条5.1 现象打包成功但运行闪退无报错原因最常见的是--onefile模式下程序运行时需要解压到临时目录如果脚本里用了相对路径读文件解压后路径就变了。另外如果目标机器缺少 VC 运行库也会闪退。解决先换成--onedir模式打包看看能不能看到报错信息。--onedir不会打包成单个文件而是生成一个文件夹里面能看到完整的依赖方便定位。如果是路径问题在代码里用sys._MEIPASS获取临时目录import sys import os def resource_path(relative_path): if hasattr(sys, _MEIPASS): return os.path.join(sys._MEIPASS, relative_path) return os.path.join(os.path.abspath(.), relative_path)5.2 现象打包体积异常大几百 MB原因全局环境里装了太多无关包PyInstaller 全扫进去了。或者用了--collect-all收集了大型库。解决确认在虚拟环境里打包检查pip list是否干净。在 spec 文件的excludes里排除明确不用的包比如matplotlib、scipy。另外upxTrue可以启用 UPX 压缩但 UPX 对某些杀毒软件不友好可能误报视情况关闭。5.3 现象报错RecursionError: maximum recursion depth exceeded原因PyInstaller 分析依赖时递归太深常见于依赖关系复杂的项目。解决在 spec 文件开头加import sys sys.setrecursionlimit(5000)然后重新打包。如果还不行检查是否有循环导入或者某个包的 hook 写得有问题尝试升级pyinstaller-hooks-contrib。5.4 现象macOS 上打包后无法运行提示“已损坏”原因macOS 的安全机制对未签名应用有限制尤其是从网络下载的。解决在目标机器上执行xattr -cr /path/to/your.app清除扩展属性。如果是要分发给别人建议做代码签名但这个涉及证书个人项目可以先跳过。5.5 现象pip install pyinstaller报权限错误原因没有在虚拟环境里装或者用了系统 Python 且没有写权限。解决激活虚拟环境再装。如果确实要装到用户目录加--user参数pip install --user pyinstaller6.3.0但我不推荐这种方式因为--user装的包路径可能不在 PyInstaller 的搜索范围内后面打包容易出玄学问题。6. 装完怎么验证跑通三个必做检查和一个打包习惯装完 PyInstaller 只是开始真正要确认的是“打出来的包能在目标环境跑”。我一般会做三个检查。检查一最小脚本打包运行。用前面那个hello.py分别用--onefile和--onedir各打一次在目标机器上运行。--onedir用来排查依赖--onefile用来确认最终分发形态。两个都跑通才算环境没问题。检查二依赖清单比对。在虚拟环境里执行pip freeze requirements_lock.txt然后和打包后build/myapp/Analysis-00.toc里的模块列表对比。如果 toc 里出现了 requirements 里没有的包说明 PyInstaller 扫到了全局环境的东西得回去检查虚拟环境是否真的隔离干净。检查三目标机器裸跑。找一台没装 Python、没装任何依赖的机器或者虚拟机把dist里的文件拷过去运行。这一步能暴露 90% 的兼容性问题。如果目标机器是 Windows Server 或者精简版系统还要注意是否缺api-ms-win-crt系列 DLL缺的话需要装 VC 运行库。最后说一个我自己的习惯每次打包前先删掉build和dist目录再执行pyinstaller myapp.spec。因为 PyInstaller 有缓存机制旧的 build 目录里可能残留上次打包的中间文件导致新包混入过期依赖。这个坑我踩过不止一次明明改了 spec 文件打出来的包行为却没变查了半天才发现是缓存没清。从那以后我每次打包都强制走一遍“清目录 → 激活虚拟环境 → 确认版本 → 打包 → 裸机验证”的流程再也没出现过那种“本地好好的换台机器就崩”的玄学问题。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/20 11:33:56 · 阅读 1.2k PyInstaller安装包避坑指南：从环境隔离到打包验证
简介PyInstaller 安装包面向需要将 Python 脚本打包为独立可执行文件的开发者尤其适合希望把项目分发给未安装 Python 环境用户的初中级工程师。资源以源码包形式提供共 19 个文件包含 10 个 txt 说明与测试文本、5 个 py 脚本、2 个 pkg-info 元数据、1 个 cfg 配置及 1 个 regen-docs 文档生成脚本压缩包约 37KB体积轻量便于快速查阅。该版本围绕依赖分析、静态链接、多平台支持与输出格式定制等核心能力组织代码并附带基础测试用例与文档目录可帮助读者理解打包工具的内部实现与配置方式。目前已有 588 人学习下载适合作为研究 Python 打包机制、排查动态库依赖与资源文件处理问题的参考素材。1. 从一次打包翻车说起pyinstaller 安装包到底怎么装才不折腾上周帮一个做桌面工具的朋友排查问题他的 Python 脚本在本地跑得好好的用 PyInstaller 打成 exe 之后换台机器就闪退连报错窗口都看不到。折腾了一下午才发现问题根本不在打包参数上而是他装 PyInstaller 的方式就不对——直接pip install pyinstaller装到了全局环境结果打包时混进了一堆无关依赖体积飙到 300 多 MB还带着一堆用不上的动态库。这个场景太常见了PyInstaller 本身安装不复杂但装错环境、装错版本、装完不验证后面打包出来的东西就是黑匣子出了问题只能靠猜。这篇笔记就把 PyInstaller 安装包这件事从头到尾捋一遍从环境隔离、版本选择、依赖补齐到装完怎么验证、坏了怎么救适合刚接触打包的新手也适合被环境问题坑过的老手。2. 装之前先把环境理清楚Python 版本、虚拟环境和依赖边界2.1 Python 版本怎么选别踩 3.12 的坑PyInstaller 对 Python 版本是有脾气 的。截至我写这篇笔记的时候PyInstaller 6.x 系列已经能比较稳定地支持 Python 3.8 到 3.12但如果你用的是 Python 3.13 或者更早的 3.7就得留个心眼。我一般会先确认当前解释器版本python --version # 或者 python3 --version如果输出是Python 3.11.x或3.12.x基本可以放心往下走。如果是 3.13建议先查一下 PyInstaller 官方 release note 里有没有明确写支持没有的话就退到 3.12 或者 3.11。为什么强调这个因为 PyInstaller 打包时要读取 Python 的字节码和动态库版本差一个小版本内部结构可能就变了打包出来的 exe 在目标机器上可能直接报ImportError或者Failed to execute script。我自己的习惯是打包用的 Python 版本尽量和目标机器上运行环境保持一致如果目标机器不确定就选一个 LTS 性质的版本比如 3.11兼容性最稳。2.2 虚拟环境不是可选项是必选项很多人图省事直接全局pip install pyinstaller然后打包。这么做不是不行但后患无穷。全局环境里装了几十个包PyInstaller 分析依赖时会把它们全扫一遍哪怕你的脚本只用了requests和tkinter它也可能把numpy、pandas的二进制文件一起塞进去最后 exe 体积爆炸启动还慢。更麻烦的是如果全局环境里某个包版本和你的脚本不兼容打包出来的东西在别人机器上跑不起来你连排查方向都没有。所以第一步先建虚拟环境。用venv就行不需要额外装东西# 在项目根目录下创建虚拟环境 python -m venv .venv # Windows 激活 .venv\Scripts\activate # macOS / Linux 激活 source .venv/bin/activate激活之后命令行前面会出现(.venv)提示。这时候再装 PyInstaller它就只在这个隔离环境里生效不会污染全局。我一般还会在项目根目录放一个requirements.txt把脚本真正依赖的包写进去比如requests2.31.0 pillow10.2.0然后pip install -r requirements.txt再装 PyInstaller。这样打包时 PyInstaller 扫描到的依赖就是干净的体积和兼容性都可控。2.3 依赖边界哪些包需要额外处理有些包 PyInstaller 不能自动识别比如用了动态导入、C 扩展、或者运行时才加载资源的库。常见的有pandas、numpy、PyQt5、opencv-python这些。装完 PyInstaller 之后如果打包报错说找不到某个模块大概率就是这类包没被正确收集。解决办法是在打包命令里加--hidden-import或者--collect-all这个后面章节会细说。但装的时候就要有意识先把脚本依赖装全再装 PyInstaller顺序反了容易漏。3. 安装 PyInstallerpip 直装、版本锁定和离线包处理3.1 标准安装流程与版本选择环境激活之后安装命令本身很简单pip install pyinstaller但我不建议直接这么装因为默认会拉最新版而最新版有时候和你的 Python 小版本有兼容问题。我一般会指定一个经过验证的版本比如pip install pyinstaller6.3.0为什么是 6.3.0这个版本对 Python 3.11 和 3.12 支持都比较稳而且修复了之前 5.x 里一些--onefile模式下的路径问题。如果你不确定用哪个版本可以先pip index versions pyinstaller看看有哪些版本然后选一个 release 时间在半年以上、没有严重 bug 报告的。装完之后验证一下pyinstaller --version # 输出类似 6.3.0如果提示command not found说明虚拟环境的 Scripts 目录没在 PATH 里或者你忘了激活环境。Windows 下可以试试python -m PyInstaller --version这个方式不依赖 PATH更稳。3.2 离线安装和国内源加速有些公司内网机器不能直连外网或者下载速度慢得让人想砸键盘。这时候有两个办法一是用国内镜像源加速二是提前下载 whl 包离线安装。镜像源加速pip install pyinstaller6.3.0 -i https://pypi.tuna.tsinghua.edu.cn/simple这个命令里的-i参数指定了清华源下载速度会快很多。如果你所在网络对特定源有限制换成阿里云或腾讯云的源也行格式类似。离线安装的话先在能上网的机器上下载 whl 包和它的依赖pip download pyinstaller6.3.0 -d ./offline_pkgs然后把offline_pkgs目录拷到目标机器执行pip install --no-index --find-links./offline_pkgs pyinstaller6.3.0--no-index表示不走网络--find-links指定本地包目录。注意 PyInstaller 依赖pyinstaller-hooks-contrib、altgraph、pefileWindows等包pip download会一并下载别只拷一个主包。3.3 安装后的目录结构确认装完之后我习惯看一眼 PyInstaller 装到哪了以及它的 hooks 目录是否完整。因为很多打包报错都和 hooks 缺失有关。python -c import PyInstaller; print(PyInstaller.__file__)输出会指向虚拟环境下的site-packages/PyInstaller/__init__.py。同级目录下应该能看到hooks文件夹里面按模块名存放了各种 hook 脚本。如果这个文件夹是空的或者缺少你用的库对应的 hook打包时就会报ModuleNotFoundError。这时候可以手动装pyinstaller-hooks-contribpip install pyinstaller-hooks-contrib这个包是 PyInstaller 官方维护的额外 hooks 集合覆盖了很多第三方库装完能省不少事。4. 配置与打包参数从 spec 文件到 hidden-import 的取舍4.1 第一次打包用命令行快速验证装好之后别急着写复杂配置先用一个最简单的脚本跑通流程。假设你有个hello.py# hello.py import sys def main(): print(Hello from PyInstaller) input(Press Enter to exit...) if __name__ __main__: main()打包命令pyinstaller --onefile hello.py--onefile表示把所有东西打成一个 exe方便分发。执行完之后当前目录会出现dist和build两个文件夹dist里就是hello.exeWindows或hellomacOS/Linux。双击运行如果能看到输出说明基础环境没问题。这一步很关键先用最小脚本验证 PyInstaller 本身能跑通再去打真实项目否则出了问题你分不清是环境问题还是项目依赖问题。4.2 spec 文件参数多了就得靠它命令行参数一多敲起来容易漏而且不好版本管理。PyInstaller 支持把配置写进.spec文件。第一次打包时加--specpath或者直接让它生成pyinstaller --onefile --name myapp hello.py执行后目录下会多一个myapp.spec。这个文件本质是个 Python 脚本内容大概长这样# myapp.spec a Analysis( [hello.py], pathex[], binaries[], datas[], hiddenimports[], hookspath[], runtime_hooks[], excludes[], noarchiveFalse, ) pyz PYZ(a.pure) exe EXE( pyz, a.scripts, a.binaries, a.datas, [], namemyapp, debugFalse, bootloader_ignore_signalsFalse, stripFalse, upxTrue, consoleTrue, )关键参数说明hiddenimports用来手动指定 PyInstaller 没自动发现的模块datas用来打包非代码文件比如配置文件、图标、模型文件excludes用来排除明确不需要的包减小体积consoleTrue表示保留控制台窗口如果是 GUI 程序可以改成False。改完 spec 文件后用pyinstaller myapp.spec重新打包不用再敲一长串命令行参数。4.3 hidden-import 和 collect-all 怎么选遇到ModuleNotFoundError时优先试--hidden-importpyinstaller --onefile --hidden-importpkg_resources myapp.spec如果某个库有一堆子模块和资源文件一个个加 hidden-import 太累就用--collect-allpyinstaller --onefile --collect-all pandas myapp.spec--collect-all会把指定包的所有子模块、数据文件、动态库都收集进来。代价是体积会变大所以只对确实需要的包用。我一般会先试 hidden-import不行再上 collect-all最后再考虑在 spec 里手动写datas和binaries。5. 避坑与排查装完打不出包时先看这几条5.1 现象打包成功但运行闪退无报错原因最常见的是--onefile模式下程序运行时需要解压到临时目录如果脚本里用了相对路径读文件解压后路径就变了。另外如果目标机器缺少 VC 运行库也会闪退。解决先换成--onedir模式打包看看能不能看到报错信息。--onedir不会打包成单个文件而是生成一个文件夹里面能看到完整的依赖方便定位。如果是路径问题在代码里用sys._MEIPASS获取临时目录import sys import os def resource_path(relative_path): if hasattr(sys, _MEIPASS): return os.path.join(sys._MEIPASS, relative_path) return os.path.join(os.path.abspath(.), relative_path)5.2 现象打包体积异常大几百 MB原因全局环境里装了太多无关包PyInstaller 全扫进去了。或者用了--collect-all收集了大型库。解决确认在虚拟环境里打包检查pip list是否干净。在 spec 文件的excludes里排除明确不用的包比如matplotlib、scipy。另外upxTrue可以启用 UPX 压缩但 UPX 对某些杀毒软件不友好可能误报视情况关闭。5.3 现象报错RecursionError: maximum recursion depth exceeded原因PyInstaller 分析依赖时递归太深常见于依赖关系复杂的项目。解决在 spec 文件开头加import sys sys.setrecursionlimit(5000)然后重新打包。如果还不行检查是否有循环导入或者某个包的 hook 写得有问题尝试升级pyinstaller-hooks-contrib。5.4 现象macOS 上打包后无法运行提示“已损坏”原因macOS 的安全机制对未签名应用有限制尤其是从网络下载的。解决在目标机器上执行xattr -cr /path/to/your.app清除扩展属性。如果是要分发给别人建议做代码签名但这个涉及证书个人项目可以先跳过。5.5 现象pip install pyinstaller报权限错误原因没有在虚拟环境里装或者用了系统 Python 且没有写权限。解决激活虚拟环境再装。如果确实要装到用户目录加--user参数pip install --user pyinstaller6.3.0但我不推荐这种方式因为--user装的包路径可能不在 PyInstaller 的搜索范围内后面打包容易出玄学问题。6. 装完怎么验证跑通三个必做检查和一个打包习惯装完 PyInstaller 只是开始真正要确认的是“打出来的包能在目标环境跑”。我一般会做三个检查。检查一最小脚本打包运行。用前面那个hello.py分别用--onefile和--onedir各打一次在目标机器上运行。--onedir用来排查依赖--onefile用来确认最终分发形态。两个都跑通才算环境没问题。检查二依赖清单比对。在虚拟环境里执行pip freeze requirements_lock.txt然后和打包后build/myapp/Analysis-00.toc里的模块列表对比。如果 toc 里出现了 requirements 里没有的包说明 PyInstaller 扫到了全局环境的东西得回去检查虚拟环境是否真的隔离干净。检查三目标机器裸跑。找一台没装 Python、没装任何依赖的机器或者虚拟机把dist里的文件拷过去运行。这一步能暴露 90% 的兼容性问题。如果目标机器是 Windows Server 或者精简版系统还要注意是否缺api-ms-win-crt系列 DLL缺的话需要装 VC 运行库。最后说一个我自己的习惯每次打包前先删掉build和dist目录再执行pyinstaller myapp.spec。因为 PyInstaller 有缓存机制旧的 build 目录里可能残留上次打包的中间文件导致新包混入过期依赖。这个坑我踩过不止一次明明改了 spec 文件打出来的包行为却没变查了半天才发现是缓存没清。从那以后我每次打包都强制走一遍“清目录 → 激活虚拟环境 → 确认版本 → 打包 → 裸机验证”的流程再也没出现过那种“本地好好的换台机器就崩”的玄学问题。希望帮到你。本文还有配套的精品资源点击获取