企业官网建设流程全解析

简介：面向需要在Windows离线环境部署Python打包工具的开发者，这份压缩包提供PyInstaller及其最小化依赖的本地安装材料，重点解决无外网、目标机器不便配置Python环境时的工具获取与依赖补齐问题，适合具备基础Python使用经验、需要交付独立可执行程序的读者。压缩包为zip格式，整体约6.21MB；上游未给出文件总数与文件类型明细，因此不宜据此判断内部条目数量，但可确认其内容围绕Windows API访问、依赖图分析、PE可执行文件读写及Python版本兼容等环节组织，覆盖打包过程中常见的依赖处理需求。已有878人学习或下载，说明该离线方案在同类场景中具有一定参考价值。读者可据此获得一套可直接用于离线部署的PyInstaller依赖集合，并借由各组件职责理解打包时依赖缺失、模块分析异常与可执行文件处理等问题的排查方向，减少在无网络环境中反复寻找依赖的时间成本。

1. 装 PyInstaller 卡在第一步：不是包坏了，是打出来的包名对不上

上个月在一台内网构建机上复现过一个典型场景。Python 是 3.12，同事把 pyinstaller依赖包.zip 解压出来，直接pip install pyinstaller，红字刷了一屏：Could not find a version that satisfies the requirement pyinstaller。他以为是包下坏了，重下三遍，最后发现问题出在文件名上——压缩包里那批 whl 写的是cp39，跟机器上的 3.12 解释器根本对不上。这种事在离线环境里特别多：能联网的时候pip会自己挑合适的轮子，断网之后挑轮子这件事得你自己干。更麻烦的是第二关：包装上了，打出来的 exe 在别人机器上闪退，日志一句没有。这篇内容适合手上有这份离线依赖包、需要在无外网机器上把 pyinstaller 装起来并打出可分发程序的人，也适合那些已经装上了、但每次打包都靠运气的人。

2. 环境对齐：Python 小版本、ABI 与 PyInstaller 6.x 的配对

离线装 PyInstaller，装不上的原因九成不在包本身，而在于“解释器身份”和“轮子标签”这两件事没对上。PyInstaller 不是一个纯 Python 的库，它内部要把 bootloader 二进制塞进产物里，还要解析目标平台的可执行文件格式，所以它对解释器版本、位数、操作系统 ABI 都很敏感。同一份 zip，在 3.9 的 64 位 Windows 上能一把装好，换到 3.12 或者 32 位解释器上就会报找不到匹配版本。先把机器摸清楚，再谈安装。

2.1 三条命令摸清解释器的真实身份

不要凭印象判断版本。很多人以为自己装的是 3.11，实际上 PATH 里排在前面的那个 python 是 IDE 自带的 3.9，pip又是另一份，这种情况在 Windows 上尤其普遍，血泪经验是先用绝对路径把三条命令跑一遍再动手。

# 1) 版本 + 编译器 + 位数，一次看全 python -VV # 2) 平台标记，决定 wheel 文件名里的 win_amd64 / linux_x86_64 / macosx_arm64 python -c "import sysconfig; print(sysconfig.get_platform())" # 3) 解释器 ABI 标签，对应 wheel 文件名里的 cp39 / cp312 python -c "import sys; print(sys.implementation.cache_tag)"

第一条输出的形态通常是Python 3.12.3 (main, ...) [MSC v.1938 64 bit (AMD64)]，方括号里那段就是位数和架构，32 bit和64 bit决定了你要的是win32还是win_amd64的轮子，两者绝对不能混装。第二条在 Windows 上给win-amd64，在 Linux 上给linux-x86_64，在 Apple 芯片的机器上给macosx-14.0-arm64。第三条给cpython-312，把前面的cpython-去掉再拼上平台标记，就是cp312-win_amd64，这正是 whl 文件名中间那段。

如果不想一条条对，让 pip 自己把兼容标签列出来更直接：

# 列出当前解释器能接受的 wheel 标签，按优先级从高到低 python -m pip debug --verbose

输出里的Compatible tags:后面会跟一长串，前十几个是精确匹配的，往后才是py3-none-any这种纯 Python 通用包。拿这份列表去比对压缩包里 whl 的文件名，能匹配上的才是能装的。顺带一提，Apple 芯片上如果 python 是在 Rosetta 下装的 x86_64 版本，get_platform()会老老实实报x86_64，打出来的包也只能在 Intel 架构上跑，这个坑在 M 系列机器上很常见。

2.2 PyInstaller 6.x 的依赖闭包与平台专属包

PyInstaller 自己不是孤立的，它的安装依赖分两层：一层是全平台都要的，一层是分平台的。离线包如果不完整，症状往往不是“装不上”，而是“装上了但打包时莫名其妙出错”，后者排查成本高得多。

表里最容易被忽略的是pyinstaller-hooks-contrib。它跟主包是分开发版的，压缩包里如果只给了 PyInstaller 本体，你照样能打出包来，但第三方库的资源文件、动态导入的模块全都会漏掉。表现是开发机上跑得好好的，打出来的 exe 换个目录就报FileNotFoundError，翻遍源码也找不到 bug——因为问题根本不在源码里。另一个是setuptools：Python 3.12 起 venv 默认不再预装它，distutils也从标准库里移除了，而不少老项目还在import pkg_resources，离线环境里这一条能让产物百分之百起不来。

验证依赖是不是齐的，可以在真正安装之前先做一次试运行。pip 22.2 之后的版本支持--dry-run，老版本退化成先装到临时 venv 里试：

# 不落盘，只让 pip 判断能不能满足依赖 python -m pip install --no-index --find-links=./wheels --dry-run pyinstaller

--no-index的意思是彻底不去联网，--find-links指向本地目录，--dry-run只解析不执行。三者一起用，能在半分钟内告诉你是“缺包”还是“标签不匹配”：前者报No matching distribution found for altgraph，后者报Could not find a version that satisfies the requirement pyinstaller，两种错误对应的处理方式完全不同。

2.3 版本配对：别拿最新解释器去喂旧轮子

版本选择的经验值是：Python 3.8 到 3.12 用 PyInstaller 6.x 都没问题，3.7 及以下只能退回 5.x 系列，3.13 需要较新的 6.x 才行。打包机我一般锁在 3.10 或 3.11，这两个小版本生态最稳，第三方库的 hook 覆盖也最全。把打包机升到最新 Python 的收益，通常抵不上某个 C 扩展还没出对应轮子的代价。

定好版本之后，把依赖固化成一份清单，比每次手敲包名靠谱得多：

# requirements-offline.txt —— 版本号按压缩包里实际有的写，不要凭空指定 pyinstaller==6.* pyinstaller-hooks-contrib==2024.* altgraph>=0.17 packaging>=21.3 setuptools>=68 pefile>=2023.2.7 ; sys_platform == "win32" pywin32-ctypes>=0.2.2 ; sys_platform == "win32" macholib>=1.16 ; sys_platform == "darwin"

行尾的分号后面是环境标记，pip 会根据当前平台决定装不装这一行。这种写法的好处是同一份清单可以在 Windows 和 Linux 的构建机上共用，不用维护两套。注意版本号里的6.*这类通配符只是示意，实际写的时候要对齐压缩包里真实存在的版本，否则 pip 会在本地目录里找一圈然后告诉你没有匹配项——这种报错信息很长，但核心就一句：本地没有你要的那个版本。

3. 离线安装：从解压到 pyinstaller 命令可用

环境对齐之后，安装本身只有三步：建干净的环境、把 whl 摊平成 pip 能认的目录、用--no-index装。每一步都不复杂，但顺序错了会很麻烦，尤其是“先装了一半再去补依赖”这种情况，最后往往要推倒重来。

3.1 先建一个干净虚拟环境，别在全局环境里打

PyInstaller 的工作方式是扫描当前环境里所有能被导入的模块，然后按依赖关系把用到的挑出来。环境越脏，它扫到的东西越多，产物越胖，冲突概率越高。全局环境里躺着的旧版本 numpy、另一套 PyQt，都可能被误收进包里。

# 用与打包机相同的小版本创建环境 python -m venv .venv-build # Windows 激活 .venv-build\Scripts\activate # Linux / macOS 激活 source .venv-build/bin/activate # 确认激活生效：路径应该指向 .venv-build 内部 python -c "import sys; print(sys.prefix)"

python -m venv比virtualenv更保险的地方在于它跟着当前解释器走，不会悄悄换一个版本。sys.prefix打印出来的路径必须是刚建的那个目录，如果还是系统路径，说明激活没生效，后面所有安装都会落到全局环境里，白忙一场。

用 conda 的人要注意一点：conda 环境里常常混着 conda 渠道和 pip 渠道两套包，如果 pyinstaller 从 conda 装一份、pip 又装一份，会出现两套 hook 目录互相看不见的情况，排查起来相当玄学。常见做法是 conda 只管创建解释器，PyInstaller 一律走 pip 装，别混渠道。

# 只要解释器，别让 conda 顺手把 pyinstaller 也装上 conda create -n build python=3.11 pip -y conda activate build

产物体积这件事在 conda 环境里格外明显：conda 装的科学计算包会带一堆.pyd和 DLL，PyInstaller 会照单全收。如果你的产物无端大了几百兆，先怀疑环境不干净，而不是怀疑 PyInstaller 本身。

3.2 把散落的 whl 摊平成一个本地索引目录

--find-links只认一个目录下的轮子，不会递归去翻子目录。压缩包解出来如果按包名分了文件夹，得先摊平。

# 建目标目录，把整棵树里的 whl 全部拷进来 mkdir -p wheels find . -name "*.whl" -exec cp {} wheels/ \; # 顺手确认一下数量，少了就是拷漏了 ls wheels/*.whl | wc -l

Windows 上换成 PowerShell：

New-Item -ItemType Directory -Force -Path .\wheels Get-ChildItem -Recurse -Filter *.whl | Copy-Item -Destination .\wheels\ (Get-ChildItem .\wheels\*.whl).Count

摊平之后，如果不同 Python 版本的轮子混在一个目录里（比如既有cp39又有cp312），不用挑出来删。pip 会自己按兼容标签筛选，不匹配的直接跳过。但不要把同名不同版本的包放在一起，那种情况下 pip 的选版行为依赖文件名排序，选出来的未必是你想要的那个，属于典型的定时炸弹。

3.3 用 --no-index 装，并做三项验收

# 离线安装主包，依赖由 pip 从同一目录解析 python -m pip install \ --no-index \ --find-links=./wheels \ --only-binary=:all: \ -r requirements-offline.txt

三个参数各管一件事。--no-index关掉网络索引，避免 pip 在超时上浪费几分钟；--find-links告诉它去哪儿找；--only-binary=:all:是关键，它禁止 pip 退回到源码包去现编译——离线机器上没有编译器和头文件，一旦走到编译分支就是一堆看不懂的 C 报错。加上这个参数，缺轮子会直接报“找不到”，错误信息干净得多。

装完做三项验收，缺一项都别急着往下走：

# 1) 版本与入口：命令和模块两种调用方式都要通 python -m PyInstaller --version # 2) hook 包是否落位，这是第三方库能不能正确打包的前提 python -c "import _pyinstaller_hooks_contrib, os; print(os.path.dirname(_pyinstaller_hooks_contrib.__file__))" # 3) 依赖一致性检查，有没有半装状态 python -m pip check

第一条如果报No module named PyInstaller，说明装到了别的解释器里，回去看 3.1 的sys.prefix。第二条打印的路径必须在虚拟环境目录内部，跑到用户目录下的site-packages就说明装串了。第三条输出No broken requirements found.才算干净。

提示：模块名是PyInstaller（大小写敏感），命令名是pyinstaller（全小写）。Linux 上敲python -m pyinstaller会直接报找不到模块，这个细节坑过不少人。

4. 打包配置：spec 文件里那几个字段怎么填

装好之后，真正的分水岭在配置。PyInstaller 支持两种用法：一长串命令行参数，或者一个 spec 文件。命令行适合一次性试验，spec 适合长期维护。判断标准很简单——同一个项目要打第二次，就该把它固化成 spec。

4.1 命令行参数与 spec 文件的分工

第一次打包我一般用命令行生成 spec，顺便把常用参数试出来：

# 第一次：生成 spec，同时把资源目录和模块搜索路径带上 pyinstaller \ --noconfirm \ --clean \ --name demo \ --onedir \ --paths ./src \ --add-data "assets;assets" \ main.py

--noconfirm让 PyInstaller 直接覆盖dist目录而不询问，适合脚本化；--clean清掉上一次的缓存，改了依赖之后必须加，否则会拿着旧的分析结果重新组装；--name决定产物名；--paths把./src加进模块搜索路径，等价于运行时改sys.path；--add-data把资源目录搬进包里。生成出来的demo.spec就在当前目录，之后所有的调整都改这个文件。

这里有个版本差异必须提：--add-data的分隔符在 5.x 及更早版本里一律是冒号，6.x 开始按平台走，Windows 上用分号、Linux 和 macOS 上用冒号。跨平台 CI 上如果不注意，Linux 那边会把冒号后面的内容当成目标路径的一部分，打出来的包里多出一个奇怪的目录。拿不准就先pyinstaller --help看一眼示例，比猜快。

改完 spec 之后，重新打包只需要：

# 后续：直接读 spec，命令行里再加参数不会覆盖 spec 的内容 pyinstaller --noconfirm --clean demo.spec

第二遍开始，命令行上再堆--add-data是没用的，因为 spec 里已经写死了datas。这个误解很普遍，很多人一边改 spec 一边在命令行加参数，然后困惑为什么改了没生效。

4.2 datas、binaries、hiddenimports 三处最容易写错的地方

spec 文件本质是一个 Python 脚本，被 PyInstaller 执行一遍来构建产物。新手看到一堆函数调用会发怵，其实只需要盯住Analysis里的四个字段。

# demo.spec —— 6.x 结构，注意 COLLECT 里不再有 zipfiles 这一项 a = Analysis( ['main.py'], pathex=['src'], # 模块搜索路径，等价于命令行的 --paths binaries=[], # 需要原样带走的动态库，一般留空 datas=[('assets', 'assets')], # (源路径, 包内目标目录) 元组 hiddenimports=[ # 静态分析看不到的模块，必须点名 'pkg_resources', 'sqlalchemy.dialects.sqlite', ], hookspath=[], excludes=['tkinter', 'matplotlib'], # 明确排除，压体积最有效的一招 noarchive=False, ) pyz = PYZ(a.pure) exe = EXE( pyz, a.scripts, [], exclude_binaries=True, # onedir 模式下二进制不塞进 exe name='demo', console=True, # 排查阶段一定要 True ) coll = COLLECT(exe, a.binaries, a.datas, name='demo')

datas是元组列表，第一个元素是磁盘上的源路径，第二个是包内的目标目录。写成('assets', 'assets')表示把整个assets目录原样放到产物根目录下的assets里。写成('config.ini', '.')则是把单个文件放到根目录。路径分隔符统一用正斜杠，Windows 上也一样，反斜杠会被当成转义符。

hiddenimports解决的是“代码里没有 import 语句但运行时需要”的情况。典型的三种：用importlib.import_module动态加载的插件、通过字符串拼出来的模块名、以及 SQLAlchemy 那种在__init__里做条件导入的库。判断方法很直接——在干净的 venv 里跑一遍程序，报哪个模块缺失就往里加哪个。别一上来就--collect-all，那会把整个包连同测试数据、示例代码全收进来。

excludes是压体积最见效的一处。tkinter、matplotlib、PyQt5这类大块头，只要代码里没用到就明确排掉。一个典型的桌面小工具，光排掉tkinter和matplotlib就能从一百多兆降到三十兆以内。

如果程序要读包内的资源文件，路径不能写死成相对当前工作目录，得用冻结后的运行目录：

import os import sys def res_path(rel: str) -> str: # 打包后资源被解到 sys._MEIPASS，未打包时退回脚本所在目录 base = getattr(sys, '_MEIPASS', os.path.dirname(os.path.abspath(__file__))) return os.path.join(base, rel) print(res_path('assets/logo.png'))

sys._MEIPASS是 PyInstaller 注入的属性，onefile 模式下指向临时解压目录，onedir 模式下指向产物根目录，未打包时不存在，所以用getattr给个默认值。硬编码./assets/logo.png的程序在开发机上永远正常，双击 exe 就崩，这是最经典的翻车姿势之一。

4.3 onefile 和 onedir 怎么选

选择上我的习惯是：内部工具、需要频繁迭代的，一律 onedir，改一行代码重打一次只要十几秒，而且崩了能看到缺哪个文件；对外交付、对方明确要求“就给我一个文件”的，才用 onefile，并且提前告知首次启动会慢两三秒。onedir 模式下从 6.x 开始产物里会多一层_internal目录，可执行文件在外面，资源在里面，看到别慌，这是正常的结构变化。

5. 避坑排查：五类翻车现场的定位路径

打包这件事的难点从来不是“怎么打”，而是“打出来为什么不能用”。下面五条是我实际遇到过、并且反复在别人机器上重现的，每条都按现象、原因、解决三段记。

5.1 装不上和打不出：前三条

现象一：ERROR: Could not find a version that satisfies the requirement pyinstaller，或者No matching distribution found for altgraph。

原因：本地目录里没有与当前解释器 ABI 匹配的轮子。要么 whl 的cpXX与解释器版本不一致，要么平台标记不一致（32 位解释器去装win_amd64），要么 pip 版本太老读不懂新标签。

解决：跑pip debug --verbose拿到兼容标签列表，和 whl 文件名逐一比对。版本对不上就换解释器或换轮子，别试图用--ignore-requires-python硬装，装进去也是坏的。同时确认 pip 本身不是太老的版本，python -m pip --version低于 20 的建议先想办法升级。

现象二：打包过程一路绿灯，双击 exe 一闪而过，命令行运行报Failed to execute script 'main'，看不到具体 traceback。

原因：多半是console=False把标准错误吞掉了，真正的异常是某个 hidden import 缺失或者资源文件读不到。

解决：把 spec 里的console改回True重新打一次，让 traceback 打出来；或者直接在 cmd / 终端里运行 exe，标准错误会输出到终端。定位到具体模块后加进hiddenimports。这个改法很土但每次管用，我一般默认先出 console 版本，验收通过再切成无窗口。

现象三：产物在开发机正常，拷到另一台机器报ModuleNotFoundError: No module named 'pkg_resources'。

原因：Python 3.12 的 venv 默认不预装 setuptools，distutils也从标准库移除了。项目里只要有一处import pkg_resources或者依赖链里有老库用了distutils，就会在目标机器上炸。

解决：在构建环境里显式装上 setuptools（离线包里有就本地装），并在 spec 的hiddenimports里补上pkg_resources。长期方案是把pkg_resources换成importlib.metadata，但那属于改代码的活，赶发布的时候先用前一种。

5.2 打出来跑不起来：后两条与日志入口

现象四：PermissionError: [WinError 5] Access is denied: 'dist\\demo.exe'，或者dist目录怎么都删不掉。

原因：上一次打出来的 exe 还在后台跑着，文件被占用；也可能是杀软正在扫描刚生成的可执行文件，短暂锁住了句柄。

解决：任务管理器里结束残留进程，然后手动删掉build和dist两个目录再重打。脚本化构建时一定带--noconfirm，否则它会卡在交互询问上直到超时。如果每次都是同一时间段失败，把项目目录加进杀软的排除列表，比反复重试有效。

现象五：RecursionError: maximum recursion depth exceeded，或者打包耗时十几分钟、产物三百多兆。

原因：前者的诱因通常是某个包的__init__里有递归导入，PyInstaller 顺着依赖图一路追下去就爆栈；后者几乎都是环境不干净，把全局环境里用不到的科学计算库、另一套 GUI 框架全扫了进来。

解决：体积问题回到 3.1，用干净的 venv 重来，并在excludes里点名排掉不用的包。递归问题先在 spec 顶部把递归上限抬高一档，再逐个排除可疑模块缩小范围：

# 放在 spec 文件最前面，仅用于绕过分析阶段的深递归 import sys sys.setrecursionlimit(10000)

这是绕过而不是修复，能用就行，别指望它解决根因。

日志在哪儿看，这一点比上面五条都重要。分析阶段的缺失模块清单会写到build/<name>/warn-<name>.txt，里面几十上百条missing module named xxx绝大多数是无害的可选导入（比如 Windows 上缺posix），只需要盯你自己项目里的模块名和核心第三方库。想看更细的过程，加--log-level=DEBUG重跑一次，输出里会明确写出每个 hook 的加载情况。build/<name>/下还有一个xref-<name>.html，用浏览器打开能查某个模块是被谁引进去的，排查“为什么这个包会被打进来”时特别好用。

注意：--clean会清掉build目录，日志跟着一起没。排查阶段先别加这个参数，等定位完了再清。

6. 装完怎么验证：用最小样例走一遍全链路

装完就跑去打真实项目，是最容易把环境问题误判成代码问题的方式。我习惯先做一次最小样例验证，把“解释器、依赖、hook、资源路径”四件事一次性验完，通过了再上真项目。

样例只做三件事：打印一行文本、读一个资源文件、输出冻结状态。

# smoke/main.py —— 最小验证样例 import os import sys def res_path(rel: str) -> str: base = getattr(sys, '_MEIPASS', os.path.dirname(os.path.abspath(__file__))) return os.path.join(base, rel) print('frozen:', getattr(sys, 'frozen', False)) print('bundle dir:', getattr(sys, '_MEIPASS', 'not frozen')) print('resource:', open(res_path('hello.txt'), encoding='utf-8').read().strip())

配合一个smoke/hello.txt，然后pyinstaller --noconfirm --onedir --name smoke --add-data "hello.txt;." smoke/main.py。打完把整个dist/smoke目录拷到一个没有装 Python、也不在源码目录下的路径去运行，这一步是关键——留在源码目录里跑，解释器可能从当前目录蒙对模块，本机有 Python 也会掩盖缺失的 DLL。

验收看五项，缺一项都算没过：

五项全绿，再拿真实项目按同样的流程走：干净 venv → 装离线包 → 生成 spec → 改datas和hiddenimports→ 出 console 版本验收 → 切无窗口 → 换机器复测。这套流程本身不复杂，麻烦的是每次都有人跳步。

从那以后我每次打完包，都会强制把产物拷到一台干净的机器上跑一遍最小样例，再把warn-<name>.txt从头翻到尾——不是不信任自己的配置，是被“本机好好的、别人一打开就闪退”坑过太多次，那种没有日志的崩溃，排查成本远高于多花五分钟做验证。希望帮到你。

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