pyinstaller打包常用参数解释.md

以下是 PyInstaller 打包时常用的参数及其解释，帮助你更好地控制打包过程：

---

1. 基本打包参数

参数	说明
-F 或 --onefile	打包成单个可执行文件（.exe）
-D 或 --onedir	打包成文件夹（默认，包含多个文件）
-w 或 --windowed	不显示控制台窗口（适用于 GUI 程序）
-c 或 --console	显示控制台窗口（默认，适用于命令行程序）
-n NAME 或 --name NAME	指定生成的可执行文件名称

示例：

pyinstaller -F -w app.py  # 打包成单个.exe，不显示控制台
pyinstaller -D -c app.py  # 打包成文件夹，显示控制台

---

2. 路径与资源文件

参数	说明
--add-data <SRC;DEST>	添加额外文件（如图片、配置文件） Windows 格式：--add-data "data/file.txt;." Linux/macOS 格式：--add-data "data/file.txt:."
--add-binary <SRC;DEST>	添加二进制文件（如 .dll, .so）
--distpath DIR	指定输出目录（默认 ./dist）
--workpath DIR	指定临时工作目录（默认 ./build）
--specpath DIR	指定 .spec 文件生成目录

示例：

pyinstaller -F --add-data "config.json;." --add-data "images;." app.py

---

3. 依赖与优化

参数	说明
--hidden-import MODULE	手动添加 PyInstaller 未能自动检测的模块
--exclude-module MODULE	排除不需要的模块（减小体积）
--upx-dir DIR	指定 UPX 压缩工具路径（需单独下载 UPX）
--noconfirm	覆盖输出目录时不提示确认

示例：

pyinstaller -F --hidden-import pandas --exclude-module matplotlib app.py

---

4. 调试与日志

参数	说明
--debug	打包时包含调试信息
--log-level LEVEL	设置日志级别（DEBUG, INFO, WARN, ERROR）

示例：

pyinstaller -F --log-level DEBUG app.py

---

5. 高级用法

生成 .spec 文件后修改

1. 先生成 .spec 文件：

   pyinstaller -F app.py
   

2. 编辑 app.spec 文件（如修改 datas 或 hiddenimports）。
3. 通过 .spec 文件打包：

   pyinstaller app.spec
   

使用 UPX 压缩

pyinstaller -F --upx-dir=/path/to/upx app.py

---

6. 常见问题解决

问题1：打包后程序闪退

• 原因：控制台程序未暂停，或 GUI 程序缺少 --windowed。
• 解决：
  • 命令行程序：在代码末尾添加 input() 或 os.system('pause')。
  • 打包时加 --console：

    pyinstaller -F --console app.py
    

问题2：缺少依赖模块

• 解决：用 --hidden-import 手动添加：

  pyinstaller -F --hidden-import=missing_module app.py
  

问题3：文件路径错误

• 解决：使用 sys._MEIPASS 访问打包后的资源路径：

  import os
  import sys
  
  if getattr(sys, 'frozen', False):
      base_path = sys._MEIPASS
  else:
      base_path = os.path.dirname(__file__)
  
  file_path = os.path.join(base_path, "data/file.txt")
  

---

完整示例

# 打包成单个.exe，添加数据文件，排除测试模块，使用UPX压缩
pyinstaller -F \
    --name "MyApp" \
    --add-data "config.json;." \
    --add-data "images;images" \
    --hidden-import=some_module \
    --exclude-module=pytest \
    --upx-dir=/path/to/upx \
    --windowed \
    app.py

---

总结

• 单文件打包：-F
• 隐藏控制台：-w（GUI 程序）
• 添加资源文件：--add-data
• 解决依赖问题：--hidden-import
• 调试：--log-level DEBUG

通过合理组合这些参数，可以灵活控制 PyInstaller 的打包行为。