简介：「pyinstaller依赖包.zip」面向需要在离线或内网环境中部署Python应用的开发者，提供Windows平台下PyInstaller的离线安装资源。包内以PyInstaller本体及其最小化依赖为核心，涵盖pywin32-ctypes的Windows API支持、altgraph的依赖图分析、future的Python 2/3兼容处理，以及pefile对PE可执行文件的读写修改，共同支撑脚本到独立可执行文件的打包流程。压缩包整体约6.21MB，文件类型明细上游暂未提供，解压后按说明配置环境变量与路径即可逐项安装组件。已有878人学习下载，适合初次接触打包、需要在无网络机器上快速搭建打包环境的中级Python使用者，也可作为排查打包依赖缺失的参考资料。

1. 为什么一个 pyinstaller依赖包.zip 能救活离线打包：先看清它到底装了什么

一个 pyinstaller依赖包.zip 最容易让人误判的地方，是把它当成“解压即装”的普通压缩包；真正卡人的往往是解释器位数、wheel 平台标签和 PyInstaller 的 hook 版本对不上。这个压缩包解决的是离线环境里 pyinstaller 及其依赖链的安装问题，适合内网构建机、交付现场不能联网的 Windows 打包场景，也适合想把打包环境做成可复现基线的人。它不是把 .py 变成 .exe 的魔法包，装完依赖之后，隐藏导入、数据文件、DLL 收集仍然要在 spec 和 hook 里逐个落地。

2. 拆包与离线安装：把 wheel 依赖链装进隔离环境

拿到压缩包先别急着往全局 site-packages 里倒。wheel 是带元数据的构建产物，pip 需要解析依赖关系、检查平台标签、决定装哪个版本；直接解压覆盖，轻则装出一套“看着能用、打包时缺模块”的环境，重则把系统里原本的包版本搅乱。我一般会先建一个干净虚拟环境，把压缩包当成离线 wheelhouse，用--no-index切断网络源，再让 pip 从本地目录解析安装。这样装出来的依赖链和交付时的构建环境一致，后面查问题时也不会被全局包干扰。

2.1 先验证压缩包结构：whl、tar.gz 与平台标签

第一步不是安装，是看压缩包里到底有什么。常见内容是pyinstaller主包、pyinstaller-hooks-contrib、altgraph、pefile、pywin32-ctypes、setuptools一类的 wheel，也可能混有源码包。源码包在离线环境里需要本地编译，构建机上如果没有编译器就会卡住，所以我会先列目录，确认 wheel 文件名里的平台标签和当前解释器对得上。

# 列出压缩包内容，重点看 .whl 文件名里的 cp 标签和 win_amd64 这类平台标签 unzip -l pyinstaller依赖包.zip # 如果当前目录已经解压，直接按文件名筛 wheel find ./deps -maxdepth 1 -name "*.whl" -printf "%f\n" | sort

unzip -l只读目录，不会改动文件；find里的-maxdepth 1避免递归进子目录，-printf "%f\n"只输出文件名，方便肉眼比对。wheel 文件名一般长成包名-版本-cp标签-abi标签-平台标签.whl，其中cp后面的数字要和解释器主版本匹配，win_amd64要和 64 位 Windows 匹配。文件名里出现none-any的是纯 Python 包，平台限制少；出现cp加平台标签的，装错版本会在 pip 解析阶段直接报“not a supported wheel on this platform”。

这一步还能提前发现压缩包里有没有重复包。比如同一个依赖放了两个不同平台的 wheel，pip 在离线目录里会按当前标签挑，一般不会装错，但目录会变乱，后续做 wheelhouse 基线时容易把无关文件带进去。我的习惯是解压后单独建一个deps目录，只保留当前构建机可用的 wheel，源码包和无关平台的包移到deps-archive，让--find-links指向的目录保持干净。

提示：压缩包解压后先核对文件名里的 Python 主版本和系统位数，不要等到 pip 报错才回头查。

2.2 用 --no-index 建离线安装链路

离线安装的关键参数是--no-index和--find-links。前者告诉 pip 不要访问任何包索引，后者指定本地查找目录。两个参数一起用，pip 才会把本地 wheel 当作唯一来源。只写--find-links而不写--no-index，pip 仍可能去远处找包，内网环境会卡在超时上，看起来像“依赖包不全”，实际是源没切断。

# 在构建机项目目录下创建隔离环境，避免污染全局解释器 python -m venv .venv-pack # Windows 下激活；如果使用 PowerShell，执行 .\.venv-pack\Scripts\Activate.ps1 .venv-pack\Scripts\activate # 升级 pip 到当前环境自带版本即可，不强制联网 python -m pip install --upgrade pip --no-index --find-links=./deps # 从本地 wheelhouse 安装 pyinstaller 及其依赖 python -m pip install --no-index --find-links=./deps pyinstaller # 安装后做依赖一致性检查 python -m pip check

python -m venv .venv-pack创建的是独立解释器环境，后面所有安装都落在这个目录里，删掉即可回滚。--no-index是离线安装的开关，--find-links=./deps指向解压后的 wheel 目录，路径可以用相对路径，也可以写绝对路径。pip check不联网，只检查已安装包之间的依赖声明是否互相满足，能提前发现“装上了但版本要求冲突”的情况。

如果pip install报“Could not find a version that satisfies the requirement”，先看报错里提到的包名，再回到deps目录确认有没有对应 wheel，以及文件名里的平台标签是否匹配。不要急着重装 Python，多数时候是 wheel 放错了目录，或者压缩包里只有源码包。源码包在离线环境里安装会触发本地构建，构建机没有编译工具链时就会失败，所以我会优先保留 wheel，源码包只作为备选。

安装完成后不要只看pip list，还要确认 PyInstaller 自己能启动。python -m PyInstaller --version能打印版本号，说明主包和 bootloader 已经可用；如果这里就报缺模块，后面的打包命令不用试，先把依赖链补齐。另一个常见动作是python -c "import PyInstaller; print(PyInstaller.__file__)"，确认导入路径落在.venv-pack里，而不是全局环境。

2.3 锁定解释器与 pip 版本，避免 ABI 错配

离线 wheelhouse 最隐蔽的坑是解释器版本和 wheel 标签错配。构建机上可能同时装了多个 Python，命令行里python指向哪一个，决定了 pip 会挑哪个 wheel。我的做法是在项目根目录固定一个.python-version之类的说明文件，或者在构建脚本里写死解释器路径，不依赖 PATH 的默认顺序。pip 版本也要看一眼，太旧的 pip 对 wheel 标签解析和新元数据支持不完整，离线安装时可能把可用的 wheel 判成不兼容。

# check_wheel_tags.py # 作用：打印当前解释器支持的平台标签，并粗筛 deps 目录下的 wheel 是否可能匹配 import sys import sysconfig from pathlib import Path print("executable:", sys.executable) print("version:", sys.version) print("platform:", sysconfig.get_platform()) print("abi tag:", sysconfig.get_config_var("SOABI")) deps = Path("./deps") for wheel in sorted(deps.glob("*.whl")): name = wheel.name # 纯 Python 包通常带 none-any，平台限制少 if "none-any" in name: print("pure-python candidate:", name) else: print("binary candidate, check tag manually:", name)

这段脚本不安装任何东西，只把当前解释器的可执行文件、版本、平台和 ABI 标签打出来，再列出deps里的 wheel 文件名。sysconfig.get_platform()在 Windows 上一般会给出win-amd64一类结果，SOABI能帮助判断扩展模块的 ABI。纯 Python 包带none-any，一般不用太担心平台；带cp和平台标签的包要人工比对，尤其是pywin32-ctypes、pefile这类和系统调用关系密切的依赖。

如果构建机是 64 位系统，但命令行里的python指向 32 位解释器，打包出来的 exe 也会是 32 位，交付到 64 位机器上可能能跑，但调用某些系统组件时会出问题。我的习惯是在构建脚本开头打印sys.executable和sys.maxsize，把解释器路径和位数记录下来，后面排查“为什么这台机器打出来的包在另一台机器上缺 DLL”时，至少知道构建环境是什么样。

注意：不要用全局环境装完依赖再打包，隔离环境能让你在出问题时直接删目录重来，不用猜哪个全局包被覆盖了。

3. 从脚本到可执行文件：PyInstaller 的依赖收集与 spec 落地

PyInstaller 的工作不是简单把.py复制到 exe 旁边，它会从入口脚本开始分析 import 图，找到模块、包、二进制扩展和数据文件，再交给 bootloader 在运行时解压或加载。理解这一点很重要：打包成功只说明分析阶段没报错，不代表运行阶段能找齐动态导入的模块。我的习惯是先用 onedir 模式跑通，确认依赖收集没问题，再决定要不要上 onefile。onedir 的目录结构暴露得更清楚，缺什么文件一眼能看到；onefile 把东西压进一个 exe，启动时解压到临时目录，出了问题反而更难定位。

3.1 先跑通 onedir，再决定 onefile

第一次打包不要直接上--onefile。用--onedir生成一个目录，里面会有_internal或同类依赖目录，exe 和依赖文件分开摆放。这个形态启动快，缺 DLL 时能看到具体文件名，适合调试。等 onedir 版本在干净机器上能跑，再切 onefile 做交付。

# 在已激活的 .venv-pack 环境中执行 # --noconfirm 覆盖旧构建目录，--clean 清理缓存，--onedir 生成目录形态 python -m PyInstaller --noconfirm --clean --onedir --name demo main.py # 如果入口脚本需要控制台输出，保留默认 console；GUI 程序可加 --windowed # 首次调试不建议加 --windowed，否则异常信息看不到 python -m PyInstaller --noconfirm --clean --onedir --console --name demo main.py

--noconfirm避免构建目录已存在时交互询问，适合脚本化。--clean会清理 PyInstaller 缓存和临时文件，减少“上次构建残留”导致的假问题。--onedir指定目录形态，--name demo决定输出目录和 exe 名称。--console保留控制台窗口，调试阶段不要急着去掉；很多启动闪退问题就是异常发生在没有控制台的时候，日志根本没地方看。

这张表不是让你永远选 onedir，而是说明调试顺序。onedir 跑通后，切 onefile 只需要把--onedir换成--onefile，但启动路径会变成临时解压目录，任何写死的相对路径都可能翻车。我的做法是先在 onedir 下把datas、binaries、hiddenimports全部配好，再切 onefile 做一次冒烟测试，确认临时目录下的资源读取逻辑没问题。

3.2 spec 文件里要盯住的 datas、binaries、hiddenimports

命令行参数多了以后，建议直接维护 spec 文件。spec 是 Python 脚本，PyInstaller 执行它来生成构建配置。最常改的是Analysis里的几个列表：datas放数据文件，binaries放动态库，hiddenimports放分析阶段没发现但运行时要导入的模块。很多人打包后报“ModuleNotFoundError”，就是因为动态导入的模块没进 import 图，必须在hiddenimports里补。

# demo.spec # 入口脚本、资源目录和隐藏导入按项目实际情况改 a = Analysis( ['main.py'], pathex=[], binaries=[ # ('源文件路径', '打包后的目标目录') # ('libs/xxx.dll', '.') ], datas=[ # ('assets', 'assets') 表示把项目下 assets 目录整个带到包内 assets 目录 ('assets', 'assets'), ], hiddenimports=[ # 动态 import、插件式加载、框架运行时才导入的模块放这里 'pkg.submodule', ], hookspath=['hooks'], hooksconfig={}, runtime_hooks=[], excludes=[], noarchive=False, ) pyz = PYZ(a.pure) exe = EXE( pyz, a.scripts, a.binaries, a.datas, [], name='demo', debug=False, bootloader_ignore_signals=False, strip=False, upx=False, console=True, )

Analysis的第一个参数是入口脚本列表，有多个入口就都放进去。pathex是额外搜索路径，项目里有非标准包目录时用。binaries是二元组列表，左边是构建机上的源路径，右边是包内目标目录；DLL 没被自动收集时在这里补。datas同理，左边源路径，右边包内路径，目录和单文件都可以。hiddenimports只写模块名，不写文件路径，PyInstaller 会按模块名去找。hookspath指向自定义 hook 目录，后面单独讲。

EXE里的upx=False建议调试阶段保持关闭。UPX 压缩能减小体积，但会改变二进制特征，某些安全软件会敏感，启动报错也更难定位。console=True保留控制台，debug=False先别开太高，等需要看导入细节时再用--debug=imports。spec 文件的好处是参数可版本化，团队里谁打包都用同一份，不会出现“你这台机器加了--add-data，那台没加”的差异。

命令行里的--add-data在 Windows 上用分号分隔源和目标，比如--add-data "assets;assets"；Linux 和 macOS 用冒号。这个分隔符差异是跨平台构建时的常见坑。spec 文件里用元组，反而没有分隔符问题，所以跨平台项目我更愿意写 spec。

3.3 用 hook 机制补上动态导入的依赖

有些包在__init__.py里用importlib.import_module或插件机制加载子模块，PyInstaller 的静态分析看不到。每个包都手写hiddenimports很累，hook 可以按包名集中处理。hook 文件放在hooks目录，命名成hook-包名.py，PyInstaller 在分析对应包时会自动执行。

# hooks/hook-my_pkg.py # 针对 my_pkg 收集子模块、数据文件和动态库 from PyInstaller.utils.hooks import collect_submodules, collect_data_files, collect_dynamic_libs hiddenimports = collect_submodules('my_pkg') datas = collect_data_files('my_pkg') binaries = collect_dynamic_libs('my_pkg')

collect_submodules('my_pkg')会递归找出包内可导入的子模块，适合插件式包。collect_data_files('my_pkg')收集包内的非 Python 文件，比如模板、配置、模型文件。collect_dynamic_libs('my_pkg')收集动态库。三个函数都返回列表，直接赋给同名变量即可。hook 目录通过 spec 里的hookspath=['hooks']或命令行--additional-hooks-dir hooks指定。

hook 不是越多越好。把整个包的所有子模块都塞进去，包体积会涨，启动分析也变慢。我的习惯是先跑一次 onedir，运行到报错，看缺哪个模块，再决定是加hiddenimports还是写 hook。hook 适合“这个包每次打包都要补同一批东西”的场景，一次性缺一个模块，直接写进 spec 更简单。

提示：hook 文件里的包名要和实际导入名一致，目录名和导入名不一致的包，先用python -c "import 包名; print(包名.__file__)"确认。

4. 常见问题排查：五个打包翻车现场的现象、原因与解决

打包工具最让人难受的地方，是它把错误分成了“构建时报错”和“运行时才报错”两类。构建时报错至少还有堆栈，运行时闪退往往只给你一个消失的窗口。下面五类问题是我在离线依赖包环境里踩得比较多的，顺序按出现频率排，每条都按现象、原因、解决三步走。排查时先保留控制台，再谈美化，不然很多信息根本拿不到。

4.1 双击后窗口一闪而过：先让异常可见

现象是双击 exe 后窗口闪一下就消失，任务管理器里进程也没了。原因通常是入口脚本在导入阶段就抛异常，或者运行时找不到某个模块，而--windowed把控制台藏掉了，异常信息没地方输出。解决的第一步不是猜缺哪个包，而是用控制台模式重新打包，把错误暴露出来。

# 用控制台模式重打，并打开导入调试 python -m PyInstaller --noconfirm --clean --onedir --console --debug=imports --name demo-debug main.py # 运行后如果闪退，直接在命令行执行 exe，看完整 traceback .\dist\demo-debug\demo-debug.exe

--console保留控制台，--debug=imports会输出导入相关的调试信息，--name demo-debug避免覆盖正式构建。直接在 cmd 或 PowerShell 里执行 exe，异常会打印在当前终端里，比双击可靠。拿到 traceback 后，缺模块就补hiddenimports，缺文件就补datas，路径错误就改资源读取逻辑。不要在没有日志的情况下反复重打，那是在赌。

4.2 杀毒误报与体积膨胀：UPX 和单文件取舍

现象是打包后的 exe 被安全软件拦截，或者体积大得离谱。原因常见于 onefile 的自解压行为、UPX 压缩后的二进制特征，以及把整个科学计算栈都打进去。onefile 运行时要把内容解压到临时目录，这个动作本身容易被启发式规则盯上；UPX 压缩会改变可执行文件结构，误报率也会上升。解决方向是关 UPX、优先 onedir、删掉不需要的依赖。

# 关闭 UPX，改用目录形态，先排除压缩和自解压因素 python -m PyInstaller --noconfirm --clean --onedir --noupx --name demo main.py # 如果确实需要单文件，再单独评估误报和启动速度 python -m PyInstaller --noconfirm --clean --onefile --noupx --name demo-onefile main.py

--noupx禁用 UPX，--onedir避免自解压，--onefile只作为对照。体积膨胀先看 spec 里的excludes，把测试框架、文档工具、没用到的可选依赖排掉；再看datas有没有把整个数据目录打进去。误报问题没有一招通吃的解法，能做的是减少可疑特征、保留构建日志、在交付前用目标环境的安全软件做一次扫描。我的习惯是正式交付优先 onedir，确实要求单文件时才上 onefile，并且提前做误报测试。

4.3 路径与资源丢失：sys._MEIPASS 不是万能路径

现象是开发环境能读到配置文件、模型文件或图标，打包后报FileNotFoundError。原因是 onefile 运行时会把包解压到临时目录，sys._MEIPASS指向那个目录；而代码里用相对路径或os.getcwd()拼路径，运行时当前工作目录可能完全不一样。解决是把资源路径统一封装，开发环境和打包环境走同一套逻辑。

# resource_path.py import sys from pathlib import Path def resource_path(relative: str) -> Path: # onefile 运行时 PyInstaller 会把资源解压到 sys._MEIPASS base = Path(getattr(sys, "_MEIPASS", Path(__file__).resolve().parent)) return base / relative # 使用示例：不要写 open("assets/config.json") config = resource_path("assets/config.json")

getattr(sys, "_MEIPASS", ...)在打包环境取临时解压目录，在开发环境回退到当前文件所在目录。relative传相对资源路径，比如assets/config.json，不要传绝对路径。这个函数只解决“读”资源，写文件不要写到_MEIPASS里，那个目录是临时的，程序退出就没了。需要持久化的配置写到用户目录，用Path.home()或环境变量拼路径。

datas配置也要和这个路径对应。spec 里写('assets', 'assets')，代码里就读resource_path('assets/config.json')。如果 spec 写的是('assets', 'data/assets')，代码里的相对路径也要跟着改成data/assets/config.json。两边不一致是资源丢失的常见原因，改完 spec 记得同步改读取逻辑。

4.4 依赖包版本冲突：隔离环境比全局环境可靠

现象是本地能打包，换一台构建机就报某个包版本不满足，或者打包成功但运行时缺符号。原因是全局环境里混装了多个项目的依赖，离线 wheelhouse 里又放了不同版本的同一个包，pip 解析时挑了一个和代码不匹配的版本。解决是用隔离环境加锁定清单，把“这次构建用了哪些包”记录下来。

# 在隔离环境中导出锁定清单，记录实际安装版本 python -m pip freeze > requirements-lock.txt # 下次离线重建时按锁定清单安装，避免解析到别的版本 python -m pip install --no-index --find-links=./deps -r requirements-lock.txt # 检查依赖声明是否冲突 python -m pip check

pip freeze输出的是当前环境实际安装的包和版本，-r requirements-lock.txt让 pip 按清单安装，不再自由解析。离线目录里如果同一个包有多个 wheel，pip 会按清单里的版本挑；清单里没有的包不会被误装。pip check只做依赖声明检查，不做运行时验证，但能提前发现明显的版本冲突。我的习惯是每次正式构建前跑一次pip check，把输出贴进构建日志。

注意：锁定清单要跟着项目走，不要用全局环境的pip freeze，那会把你机器上无关的包也带进去。

4.5 打包成功但运行报 DLL 错：看 binaries 和 GUI 后端

现象是 exe 能启动，但一调用某个功能就报DLL load failed，或者 GUI 程序报 Tcl/Tk 相关错误。原因是二进制依赖没被收集进binaries，或者 GUI 后端、图像处理库的动态库藏在包目录里，静态分析没发现。解决是先确认缺哪个 DLL，再补binaries或用--collect-all让 PyInstaller 收集整个包。

# 让 PyInstaller 尽量收集指定包的数据、二进制和子模块 python -m PyInstaller --noconfirm --clean --onedir --collect-all my_gui_pkg --name demo main.py # 构建后到输出目录里按文件名找 DLL，确认是否被带进去 Get-ChildItem -Recurse .\dist\demo | Where-Object { $_.Name -like "*.dll" } | Select-Object FullName

--collect-all my_gui_pkg会收集该包的子模块、数据文件和二进制，适合依赖结构复杂的 GUI 或图像库。Get-ChildItem -Recurse在 PowerShell 里递归列文件，Where-Object筛 DLL，Select-Object FullName看完整路径。如果目标 DLL 不在输出目录，就在 spec 的binaries里手动补；如果 DLL 在但加载失败，用依赖查看工具看它还缺哪些上层库。Tcl/Tk 这类后端问题，优先确认打包环境里 GUI 库本身是否完整，再谈 PyInstaller 配置。

5. 让打包结果可验证：用干净机器和依赖清单做回归

打包成功不等于可交付。构建机上能跑，可能是因为系统里恰好有某个 DLL，或者全局环境里装了某个包，exe 运行时从 PATH 里找到了。要验证离线依赖包打出来的东西是否真的自包含，得把 exe 放到没有 Python、没有项目依赖的干净环境里跑。我的做法是保留三类东西：依赖锁定清单、构建日志、最小复现工程。前者说明用了什么，中间者说明构建时发生了什么，后者用来在出问题时快速缩小范围。

5.1 依赖清单与构建日志留档

依赖清单不是requirements.txt那种只写顶层包的文件，而是pip freeze导出的全量锁定清单。构建日志则要打开 PyInstaller 的日志级别，把分析阶段的警告留下来。PyInstaller 会在构建目录里生成warn-*.txt，里面记录找不到的模块、被忽略的导入和二进制收集情况。很多人只看最后一行“Build complete”，不看警告，结果运行时才缺模块。

# 导出全量依赖，记录构建环境 python -m pip freeze > build-logs/requirements-lock.txt # 提高日志级别，保留分析阶段输出 python -m PyInstaller --noconfirm --clean --onedir --log-level=DEBUG --name demo main.py 2>&1 | tee build-logs/pyinstaller-build.log # 构建后查看警告文件，按缺模块名逐个确认 Get-ChildItem .\build\demo\warn-*.txt

pip freeze的输出包含所有已安装包和版本，适合离线重建。--log-level=DEBUG让 PyInstaller 输出更详细的分析信息，2>&1 | tee同时写终端和文件，方便后面搜关键字。warn-*.txt里的“missing module named”不一定是真问题，有些是可选依赖或平台分支，但连续出现同一个包名时就要注意。我的习惯是把警告文件里和目标功能相关的模块筛出来，和hiddenimports对照，确认没有漏掉动态导入。

5.2 在无 Python 环境做冒烟测试

干净机器测试不要只双击看一眼窗口。至少要覆盖启动、核心功能、资源读取、退出码四个点。启动看有没有闪退，核心功能看依赖有没有缺，资源读取看datas路径对不对，退出码看程序是正常结束还是异常退出。能自动化就写一个小脚本，在目标机器上跑一遍，把输出和退出码记下来。

# smoke_test.py # 在目标机器上运行，前提是 exe 已经放在当前目录或指定路径 import subprocess import sys from pathlib import Path exe = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("dist/demo/demo.exe") result = subprocess.run( [str(exe), "--self-check"], capture_output=True, text=True, timeout=60, ) print("returncode:", result.returncode) print("stdout:", result.stdout[-2000:]) print("stderr:", result.stderr[-2000:]) # 退出码非 0 或 stderr 有 traceback 时，构建视为不可交付 if result.returncode != 0 or "Traceback" in result.stderr: raise SystemExit("smoke test failed")

subprocess.run启动 exe，capture_output=True收集标准输出和错误，text=True按文本处理，timeout=60防止程序卡死。入口脚本里最好提供一个--self-check参数，做最小初始化并退出，不要真的弹窗等用户操作。returncode非 0 或 stderr 出现 traceback 就判定失败。这个脚本放在构建流水线里，比人工双击可靠。

如果程序是 GUI 应用，没有--self-check，就退一步用subprocess.Popen启动，等几秒，检查进程是否还活着，再发关闭信号。这种方式不如自检参数精确，但能抓到“启动即崩”的问题。测试机器上不要装 Python，也不要装项目依赖，否则测出来的自包含性不真实。

5.3 用最小复现工程定位隐式导入

遇到“打包后缺某个模块”时，不要在整个项目里反复重打。建一个最小复现工程，只保留触发问题的入口和那个包，用同样的 PyInstaller 参数打一次。最小工程构建快，日志短，缺什么一目了然。定位到具体包之后，再回到主项目补hiddenimports或 hook。

# 最小复现工程目录结构 # repro/ # main.py # deps/ （从依赖包解压出来的 wheel） # hooks/ python -m venv .venv-repro .venv-repro\Scripts\activate python -m pip install --no-index --find-links=./deps pyinstaller my_pkg python -m PyInstaller --noconfirm --clean --onedir --console --debug=imports --name repro main.py

main.py里只写import my_pkg和一行调用，不要带业务逻辑。--debug=imports输出导入过程，--console让错误可见。最小工程能复现问题，就把它的 spec 和 hook 对照主项目改；不能复现，说明问题来自主项目的组合依赖，再逐步往最小工程里加包，直到复现为止。这个办法比在几千行项目里猜要快得多。

提示：最小复现工程也要用同一个离线 wheelhouse 和同一个解释器，否则变量太多，定位结果不可信。

6. 进阶技巧：把依赖包变成可复用的离线构建基线

离线依赖包用一次就扔很浪费。我的做法是把它整理成 wheelhouse 加锁定清单的基线：deps目录只放当前构建机可用的 wheel，requirements-lock.txt记录全量版本，spec模板和构建脚本放在项目根目录。下次换机器，复制这三样东西，建虚拟环境、离线安装、按 spec 打包，步骤固定下来，排错时也知道变量在哪。

6.1 建立 requirements 锁定与 wheelhouse 目录

不要每次从压缩包里随手解压就装。先在一个干净环境里装出可用的依赖组合，pip freeze导出锁定清单，再把pip download或压缩包里的 wheel 整理进wheelhouse。目录里只留当前平台和解释器可用的 wheel，源码包和无关平台的包移到归档目录。这样--find-links指向的目录不会出现多个版本互相干扰。

# 从锁定清单离线重建，先确认依赖能装齐 python -m venv .venv-base .venv-base\Scripts\activate python -m pip install --no-index --find-links=./wheelhouse -r requirements-lock.txt python -m pip check python -m PyInstaller --version

requirements-lock.txt是全量清单，wheelhouse是本地包目录，--no-index切断外部源。pip check和PyInstaller --version是两道门槛，过不了就不要往下打包。这个基线建好后，构建脚本里只引用清单和目录，不再依赖某台机器上的全局环境。

6.2 用 spec 模板和构建脚本固化参数

spec 文件进版本库，构建脚本只做三件事：激活环境、清理旧产物、执行 spec。命令行参数容易漏，spec 里写清楚datas、binaries、hiddenimports和upx=False，团队里谁打都一样。构建脚本里保留日志输出，方便回溯。

# build_offline.sh，在项目根目录执行 set -e source .venv-pack/Scripts/activate python -m pip check python -m PyInstaller --noconfirm --clean --log-level=DEBUG demo.spec 2>&1 | tee build-logs/last-build.log

set -e让脚本在任一步失败时退出，source激活隔离环境，pip check做依赖一致性检查，pyinstaller demo.spec按 spec 构建，tee保留日志。脚本里不写--onefile或--onedir，形态在 spec 里定，避免命令行和 spec 冲突。正式交付前，把dist目录放到干净机器跑一遍第 5 章的冒烟测试，过了再发。

6.3 版本升级时的回归清单

升级 PyInstaller 或某个依赖时，不要只打一次看能不能启动。我的回归清单是：离线安装能否完成、pip check是否通过、onedir 能否启动、核心功能是否正常、onefile 是否误报、资源路径是否可读、日志里有没有新增 missing module。每次升级按这个顺序走一遍，出问题能快速定位到是依赖包、spec 还是代码路径。

踩过的坑是只测了 onedir，没测 onefile，交付后才发现单文件版本在目标机器上被杀软拦了。从那以后我每次升级依赖包，都强制把 onedir 和 onefile 各跑一遍冒烟测试，日志和锁定清单一起归档。这份 pyinstaller依赖包.zip 我放在文末的资源入口，拿到后先按第 2 章核对目录结构，再把它整理成自己的 wheelhouse 基线，后面换机器就不用重新猜依赖了。希望帮到你。

本文还有配套的精品资源，点击获取