Pelco KBD300A 模拟器:04+2. PyInstaller 5.13.2 打包全解析

第4+2篇 PyInstaller 5.13.2 打包全解析

前言

在上一篇我们系统梳理了 Python 打包工具的历史与对比，结论是PyInstaller仍是桌面应用和现场部署的首选。本篇将专注于PyInstaller 5.13.2——这是兼顾稳定性与兼容性的版本，尤其在 Windows 7 + Python 3.7 环境下表现可靠。我们将从安装、打包模式、常用参数，到spec 文件的深度解析，全面覆盖，让你能从入门到精通。

一、PyInstaller 简介

• 跨平台支持：Windows、Linux、macOS
• 打包方式：可生成单文件（onefile）或单目录（onedir）可执行程序
• 依赖分析：自动检测并收集 Python 模块、DLL、数据文件
• 资源嵌入：支持图标、版本信息、额外数据文件
• 社区活跃：拥有丰富的钩子（hooks），能处理复杂依赖库（如 PyQt、Tkinter、matplotlib）

二、安装与环境

pipinstallpyinstaller==5.13.2

• 推荐在虚拟环境中使用，避免依赖冲突
• 兼容 Python 3.7~3.11，实测在 Windows 7 上与 Python 3.7.9 完美运行
• 打包后可在 Win7~Win11 全系列系统运行

三、打包模式

• 单文件模式（–onefile）
  • 优点：分发方便，只有一个 exe
  • 缺点：启动时需解压，速度略慢
• 单目录模式（默认）
  • 优点：启动快，资源可直接修改
  • 缺点：分发时需整个目录

最佳实践：开发调试阶段用单目录，发布阶段用单文件。

四、常用参数

• --onefile：单文件打包
• --windowed：去掉控制台窗口（适合 GUI 程序）
• --icon=xxx.ico：自定义图标
• --add-data "data;data"：添加数据文件（Windows 下用分号分隔）
• --hidden-import：解决依赖未自动识别问题
• --version-file version.txt：嵌入版本信息

五、spec 文件详解（核心部分）

相比命令行，spec 文件提供了更灵活的配置方式，适合复杂项目。打包时可直接运行：

pyinstaller myapp.spec

1. 基本结构

# -*- mode: python ; coding: utf-8 -*-block_cipher=Nonea=Analysis(['pelco_tool_v1.py'],pathex=[],binaries=[],datas=[],hiddenimports=[],hookspath=[],hooksconfig={},runtime_hooks=[],excludes=[],win_no_prefer_redirects=False,win_private_assemblies=False,cipher=block_cipher,noarchive=False,)pyz=PYZ(a.pure,a.zipped_data,cipher=block_cipher)exe=EXE(pyz,a.scripts,a.binaries,a.zipfiles,a.datas,[],name='pelco_tool_v1',debug=False,bootloader_ignore_signals=False,strip=False,upx=True,upx_exclude=[],runtime_tmpdir=None,console=True,disable_windowed_traceback=False,argv_emulation=False,target_arch=None,codesign_identity=None,entitlements_file=None,)

2. 各部分说明

• Analysis
  • 负责依赖分析，收集脚本、模块、数据文件
  • 参数datas用于添加额外资源（如配置文件、数据库）
• PYZ
  • 将 Python 字节码压缩为一个归档文件
• EXE
  • 定义最终 exe 的属性
  • 可指定图标、版本信息、是否带控制台窗口
• COLLECT
  • 收集所有文件，生成最终目录或单文件

3. 高级用法

• 添加 DLL 或二进制文件

  binaries=[('dlls/mylib.dll','.')]

• 嵌入版本信息

  version='version.txt'

• 多入口脚本
  在a = Analysis([...])中添加多个 py 文件

六、在 PyInstaller 中嵌入版本信息

1. 为什么需要版本信息？

• 在 Windows 上，右键点击 exe → 属性 → 详细信息，可以看到版本号、公司名、版权等信息。
• 这些信息有助于：
  • 区分不同版本的发布包
  • 提升专业感，避免“未知发布者”提示
  • 在企业环境中满足合规要求

2. 创建版本信息文件

PyInstaller 支持通过文本文件定义版本信息，通常命名为version.txt。内容格式类似于 Windows 的资源脚本：

# UTF-8 # PyInstaller 6.x version.txt 示例 VSVersionInfo( ffi=FixedFileInfo( filevers=(1, 0, 0, 0), # 文件版本号 prodvers=(1, 0, 0, 0), # 产品版本号 mask=0x3f, flags=0x0, OS=0x4, # Windows NT fileType=0x1, # 应用程序 subtype=0x0, date=(0,0) ), kids=[ StringFileInfo([ StringTable( '080404b0', # 简体中文 [ StringStruct(u'CompanyName', u'智码电子'), StringStruct(u'FileDescription', u'Pelco-D/P 万能现场维护工具'), StringStruct(u'FileVersion', u'1.0.0.0'), StringStruct(u'InternalName', u'pelco_tool_v1'), StringStruct(u'LegalCopyright', u'Copyright © 2025 我送炭你添花'), StringStruct(u'OriginalFilename', u'pelco_tool_v1.exe'), StringStruct(u'ProductName', u'Pelco Tool'), StringStruct(u'ProductVersion', u'1.0.0.0') ] ) ]), VarFileInfo([VarStruct(u'Translation', [0x0804, 1200])]) ] )

3. 语言设置

语言的设置主要通过StringTable的代码页和语言 ID来控制。关键点在于：

🔑 如何设置语言

• StringTable(u'040904B0', [...])
  • 前四位0409表示语言 ID（这里是美国英语，LCID=0x0409）。
  • 后四位04B0表示代码页（这里是 Unicode UTF-16）。
• VarFileInfo([VarStruct(u'Translation', [0x0409, 1200])])
  • 第一个值0x0409是语言 ID。
  • 第二个值1200是代码页（1200 = Unicode UTF-16）。

🌍 常见语言与代码页示例

4.在打包命令中使用版本信息

pyinstaller --onefile --console --icon=keyboard.ico --version-file=version.txt pelco_tool_v1.py

这样生成的 exe 文件在 Windows 属性中就会显示上述信息。

5. 在 spec 文件中嵌入版本信息

如果使用.spec文件，可以在EXE部分添加：

# -*- mode: python ; coding: utf-8 -*-block_cipher=Nonea=Analysis(['pelco_tool_v1.py'],pathex=[],binaries=[],datas=[],hiddenimports=[],hookspath=[],hooksconfig={},runtime_hooks=[],excludes=[],win_no_prefer_redirects=False,win_private_assemblies=False,cipher=block_cipher,noarchive=False,)pyz=PYZ(a.pure,a.zipped_data,cipher=block_cipher)exe=EXE(pyz,a.scripts,a.binaries,a.zipfiles,a.datas,[],name='pelco_tool_v1',debug=False,bootloader_ignore_signals=False,strip=False,upx=True,upx_exclude=[],runtime_tmpdir=None,console=True,disable_windowed_traceback=False,argv_emulation=False,target_arch=None,codesign_identity=None,entitlements_file=None,version='version.txt',icon='keyboard.ico',)

打包命令：

pyinstaller --clean --noconfirm pelco_tool_v1.spec

6. 解释与最佳实践

• filevers / prodvers：分别表示文件版本和产品版本，通常保持一致。
• CompanyName / ProductName：显示在 Windows 属性中，建议填写真实公司或项目名。
• LegalCopyright：版权声明，避免“未知发布者”。
• Translation：语言与编码，1033,1200表示英语 + Unicode。中文环境可用2052,1200。

最佳实践：

• 每次发布新版本时更新FileVersion和ProductVersion。
• 在企业或开源项目中，保持版本信息与 changelog 一致。
• 使用 spec 文件集中管理，避免命令行参数过长。

这样，你的PyInstaller 5.13.2 打包专篇就和上一篇形成了呼应：前一篇讲工具全景对比，这一篇不仅讲 PyInstaller 的打包，还深入到版本信息与 spec 文件配置，让读者能做出专业级的 exe。

七、常见问题与解决

• 启动慢：单文件模式需解压，建议用单目录或优化依赖
• 缺少 DLL：在 spec 文件中添加binaries
• 体积过大：排除不必要库，或用 UPX 压缩
• 杀毒误报：可通过签名、排除压缩解决
• Win7 兼容性：必须使用 Python 3.7 + PyInstaller 5.13.2

八、最佳实践

• 开发阶段：单目录模式，方便调试和修改资源
• 发布阶段：单文件模式，方便分发
• 使用 spec 文件集中管理资源和配置，保证可维护性
• 打包后务必在目标环境全面测试

九、总结

PyInstaller 5.13.2 是目前最稳定的版本之一，兼顾兼容性与功能。掌握其命令行参数与spec 文件配置，能让你在任何现场快速生成可靠的可执行工具。