1. 复杂 Python 项目打包 EXE 到底难在哪如果你写过带 PySide6 界面的 Python 工具本地python main.py跑得好好的一旦要交给别人用问题就来了对方没装 Python、没装依赖、模型文件路径找不到、DLL 缺失、杀软拦截。把复杂项目打包成 EXE本质上是把「解释器 三方库 资源文件 动态导入模块」全部塞进一个可执行体任何一环漏了都会在别人机器上炸。我这次面对的项目结构不算小PySide6 做界面opencv、numpy、Pillow 做图像处理torch/torchvision 做增强算法还有两个独立算法包通过动态导入加载外加.pth模型权重和cpu_version/gpu_version两套实现。用 PyInstaller 直接--onefile打第一次就卡在「build 目录里有 .pkg 但没有 .exe」日志还显示成功非常迷惑。这篇就按我实际落地的顺序把 Trae Solo 协作下的完整配置骨架拆开PyInstaller spec 怎么写、TaoToken 统一 Key/API 通道的config.toml怎么配、Inno Setup 安装脚本怎么编、最后怎么验证一次可复现的打包与安装。适合已经会用 Python、但第一次认真做 Windows 分发的人。2. 前置用 TaoToken 统一 Key 与 API 通道复杂项目里最烦的不是打包本身而是打包后应用还要调模型接口。如果每个模块各自读环境变量、各自写 base_url配置会散得到处都是。我的做法是引入 TaoToken 作为统一入口把 Key 和 API 地址收敛到一份config.toml打包时随资源一起进 EXE。TaoToken 是一个聚合式的大模型 API 接入服务兼容 OpenAI 风格的调用方式适合需要在一个项目里切换多个模型、又不想改代码的场景。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意这个地址不带任何查询参数。你需要先去控制台拿 Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到之后不要硬编码进源码而是写进配置文件打包时通过datas带进去。注意Key 属于敏感信息正式分发时建议让用户首次启动自行填写或走服务端下发不要把生产 Key 打进 EXE。3. 可复制配置spec 骨架 config.toml Inno Setup3.1 PyInstaller spec 骨架复杂项目的 spec 不能靠命令行参数堆必须落成文件。下面这份是我实际用的骨架重点在datas收集资源、hiddenimports补动态导入、excludes砍掉用不到的大块依赖。# -*- mode: python ; coding: utf-8 -*- import os project_root os.path.dirname(os.path.abspath(__file__)) added_datas [ (os.path.join(project_root, module_library, LocalAIFato_ESRGAN, models, RealESRGAN_x4plus.pth), module_library/LocalAIFato_ESRGAN/models), (os.path.join(project_root, module_library, LocalAIFato_ESRGAN, cpu_version), module_library/LocalAIFato_ESRGAN/cpu_version), (os.path.join(project_root, module_library, LocalAIFato_ESRGAN, gpu_version), module_library/LocalAIFato_ESRGAN/gpu_version), (os.path.join(project_root, module_library, multipicsenhance), module_library/multipicsenhance), (os.path.join(project_root, config.toml), .), ] hidden_imports [ realesrgan, realesrgan.utils, basicsr, basicsr.archs, basicsr.archs.rrdbnet_arch, basicsr.utils, basicsr.utils.registry, torch, torch.nn, torchvision, torchvision.transforms, cv2, cv2.cv2, module_library.LocalAIFato_ESRGAN.cpu_version.image_enhancer, module_library.LocalAIFato_ESRGAN.gpu_version.image_enhancer, module_library.multipicsenhance.image_align_stack, PIL, PIL.Image, PIL.ImageEnhance, numpy, scipy, matplotlib, ] a Analysis( [MoonPicEnhance.py], pathex[project_root], binaries[], datasadded_datas, hiddenimportshidden_imports, hookspath[], hooksconfig{}, runtime_hooks[], excludes[torch.cuda, torchvision.cuda], noarchiveFalse, optimize0, ) pyz PYZ(a.pure) exe EXE( pyz, a.scripts, [], exclude_binariesTrue, nameMoonPicEnhance, debugFalse, bootloader_ignore_signalsFalse, stripFalse, upxTrue, consoleFalse, disable_windowed_tracebackFalse, argv_emulationFalse, target_archNone, codesign_identityNone, entitlements_fileNone, ) coll COLLECT( exe, a.binaries, a.datas, stripFalse, upxTrue, upx_exclude[], nameMoonPicEnhance, )几个关键点datas里每一项是(源路径, 打包后目录)模型权重和两套算法实现都要显式带上hiddenimports必须覆盖所有动态导入的模块否则运行时报ModuleNotFoundErrorexcludes里砍掉 CUDA 相关能显著减小体积前提是你的应用不强依赖 GPU。3.2 config.toml 统一通道[taotoken] base_url https://taotoken.net/api api_key sk-你的Key default_model claude-sonnet-4-5 timeout 60 [app] model_dir module_library/LocalAIFato_ESRGAN/models use_gpu false读取时用tomllibPython 3.11或tomli路径通过sys._MEIPASS兼容打包后的临时目录import sys, os, tomllib def resource_path(rel): base getattr(sys, _MEIPASS, os.path.dirname(os.path.abspath(__file__))) return os.path.join(base, rel) with open(resource_path(config.toml), rb) as f: cfg tomllib.load(f) base_url cfg[taotoken][base_url] api_key cfg[taotoken][api_key]这样无论开发态还是打包态配置读取逻辑一致模型调用统一走 TaoToken 通道。3.3 Inno Setup 安装脚本EXE 打出来后直接发一个几百 MB 的文件体验很差用 Inno Setup 做成安装包更专业。核心脚本如下[Setup] AppNameMoonPicEnhance AppVersion1.0.0 DefaultDirName{autopf}\MoonPicEnhance DefaultGroupNameMoonPicEnhance OutputDirinstaller\output OutputBaseFilenameMoonPicEnhance_Setup_1.0.0 Compressionlzma2 SolidCompressionyes ArchitecturesInstallIn64BitModex64 [Files] Source: dist\MoonPicEnhance\*; DestDir: {app}; Flags: recursesubdirs createallsubdirs [Icons] Name: {group}\MoonPicEnhance; Filename: {app}\MoonPicEnhance.exe Name: {autodesktop}\MoonPicEnhance; Filename: {app}\MoonPicEnhance.exe [Run] Filename: {app}\MoonPicEnhance.exe; Description: 启动应用; Flags: nowait postinstall skipifsilent在 Inno Setup 里打开setup.iss菜单 Build → Compile Script 即可生成安装包。4. 验证请求与成功结果打包命令建议用虚拟环境里的解释器避免系统环境污染python -m venv venv_packaging .\venv_packaging\Scripts\python.exe -m pip install pyinstaller PySide6 opencv-python numpy Pillow scipy matplotlib .\venv_packaging\Scripts\python.exe -m PyInstaller MoonPicEnhance.spec --noconfirm --clean打包完成后检查dist\MoonPicEnhance\MoonPicEnhance.exe是否存在。运行后如果界面正常弹出、模型加载成功、调用 TaoToken 接口返回结果说明通道打通。验证模型对话是否正常可以直接在应用内触发一次请求或到 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 对照可用模型列表确认。安装包验证双击MoonPicEnhance_Setup_1.0.0.exe走完安装流程从开始菜单启动确认桌面快捷方式和程序组都正常。这一步能暴露资源路径、权限、DLL 缺失等问题。5. 本篇常见错排查5.1 build 目录有 .pkg 但没有 .exe这是最坑的一个。日志显示Building EXE from EXE-00.toc completed successfully但 dist 里就是没有 exe。我排查下来根因是 Windows Defender 实时保护在 PyInstaller 从 .pkg 转 exe 的阶段拦截了文件写入。解决方式是临时关闭实时保护Set-MpPreference -DisableRealtimeMonitoring $true打包完成后记得恢复Set-MpPreference -DisableRealtimeMonitoring $false5.2 ModuleNotFoundError: No module named emailPyInstaller 的pyi_rth_pkgres.py钩子在部分版本下会漏掉标准库email。在 spec 的hiddenimports里补上email、email.mime、email.mime.text即可。5.3 运行时报缺库缺什么补什么打包成功但运行报ModuleNotFoundError说明hiddenimports没覆盖全。我的做法是逐个补先加matplotlib再加scipy直到不再报错。也可以写一个打包前检查脚本提前验证关键模块可导入import sys def check_module(name, criticalTrue): try: __import__(name) print(fOK {name}) return True except ImportError as e: print(f{FAIL if critical else WARN} {name}: {e}) return not critical critical [torch, torchvision, realesrgan, basicsr, cv2, PIL, numpy, PySide6] ok all(check_module(m) for m in critical) sys.exit(0 if ok else 1)5.4 PySide6 单文件模式失败PySide6 依赖大量 DLL--onefile模式下解压到临时目录时容易触发路径长度限制或 DLL 冲突。实测下来--onedir模式稳定得多配合 Inno Setup 做成安装包用户体验反而更好。如果一定要单文件加上--collect-all PySide6 --collect-all shiboken6并确保disable_windowed_traceback关闭方便看错误。5.5 qtwebengine_locales 找不到如果项目没用到 QtWebEngine可以在 spec 里排除相关模块如果用到需要确保PySide6/translations/qtwebengine_locales目录被正确收集。报错Unable to find ... qtwebengine_locales时检查 PySide6 安装是否完整必要时重装。6. 长期编码与 Agent 场景的接入建议如果你不只是打包一个工具而是长期用 AI 辅助编码、跑 Agent 任务建议把 TaoToken 的 Coding Plan 纳入工作流。入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合需要稳定调用、多模型切换的持续开发场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的 API 说明和示例。Claude Code 相关的 Anthropic 兼容接入可以参考 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 。整个流程走下来我的体会是打包 EXE 的难点不在 PyInstaller 本身而在资源收集、动态导入、系统安全策略这三块。Trae Solo 在分析问题和给建议上确实有帮助但遇到系统级拦截时还是得自己动手验证。把 spec 落成文件、把配置收敛到 config.toml、把安装包交给 Inno Setup这套骨架跑通一次之后后续版本迭代就轻松多了。
