pyinstaller打包详解Ⅰ

以下是 PyInstaller 常用打包命令参数的详细说明，涵盖大多数场景下的配置需求。通过合理组合这些参数，可以优化打包结果并解决常见问题。

---

### **一、基础打包参数**
| 参数 | 说明 | 示例 |
|------|------|------|
| `--onefile` | 将程序打包成单个可执行文件（默认生成多文件目录）。 | `pyinstaller --onefile app.py` |
| `--onedir` | 生成一个目录包含所有依赖文件（默认行为，与 `--onefile` 互斥）。 | `pyinstaller --onedir app.py` |
| `--name` 或 `-n` | 指定生成的可执行文件名称（默认与脚本同名）。 | `pyinstaller --name MyApp app.py` |
| `--specpath` | 指定生成的 `.spec` 文件的存放路径。 | `pyinstaller --specpath ./specs app.py` |
| `--distpath` | 指定最终打包结果的输出目录（默认 `./dist`）。 | `pyinstaller --distpath ./output app.py` |
| `--workpath` | 指定临时构建文件的目录（默认 `./build`）。 | `pyinstaller --workpath ./temp app.py` |
| `--clean` | 清理临时文件并重新构建。 | `pyinstaller --clean app.py` |

---

### **二、文件与数据管理**
| 参数 | 说明 | 示例 |
|------|------|------|
| `--add-data` | 添加外部文件或目录到打包结果中（格式：`源路径:目标路径`）。 | `pyinstaller --add-data "assets/*.png:assets" app.py` |
| `--add-binary` | 添加二进制文件（如 `.dll` 或 `.so`），处理方式与 `--add-data` 类似。 | `pyinstaller --add-binary "lib/*.dll:lib" app.py` |
| `--collect-data` | 强制收集指定模块的数据文件（如 `--collect-data matplotlib`）。 | `pyinstaller --collect-data sklearn app.py` |
| `--hidden-import` | 手动指定隐式导入的模块（解决打包后缺失依赖问题）。 | `pyinstaller --hidden-import pandas app.py` |
| `--exclude-module` | 排除不需要的模块以减小体积（如测试库）。 | `pyinstaller --exclude-module unittest app.py` |

---

### **三、路径与依赖配置**
| 参数 | 说明 | 示例 |
|------|------|------|
| `--paths` 或 `-p` | 添加模块搜索路径（类似 `sys.path`）。 | `pyinstaller --paths "./lib" app.py` |
| `--runtime-hook` | 添加自定义运行时钩子脚本（用于动态加载资源）。 | `pyinstaller --runtime-hook hooks/hook.py app.py` |
| `--additional-hooks-dir` | 指定自定义钩子脚本的目录。 | `pyinstaller --additional-hooks-dir ./hooks app.py` |

---

### **四、窗口模式与图标**
| 参数 | 说明 | 示例 |
|------|------|------|
| `--windowed` 或 `-w` | 隐藏控制台窗口（适用于 GUI 程序，如 PyQt/PySide）。 | `pyinstaller --windowed app.py` |
| `--noconsole` | 同 `--windowed`，仅 Windows 有效。 | `pyinstaller --noconsole app.py` |
| `--icon` | 设置可执行文件的图标（Windows：`.ico`，macOS：`.icns`）。 | `pyinstaller --icon=app.ico app.py` |

---

### **五、调试与优化**
| 参数 | 说明 | 示例 |
|------|------|------|
| `--debug` | 生成调试版的可执行文件（包含调试信息）。 | `pyinstaller --debug app.py` |
| `--strip` | 移除调试符号（减小文件体积，生产环境建议启用）。 | `pyinstaller --strip app.py` |
| `--noupx` | 禁用 UPX 压缩（解决 UPX 导致的兼容性问题）。 | `pyinstaller --noupx app.py` |
| `--upx-dir` | 指定 UPX 工具的路径（默认自动查找）。 | `pyinstaller --upx-dir "C:/upx" app.py` |

---

### **六、跨平台与安全**
| 参数 | 说明 | 示例 |
|------|------|------|
| `--target-arch` | 指定目标架构（如 macOS 的 `x86_64` 或 `arm64`）。 | `pyinstaller --target-arch arm64 app.py` |
| `--key` | 使用密钥加密 Python 字节码（需安装 `tinyaes`）。 | `pyinstaller --key 123456 app.py` |

---

### **七、常用组合示例**
#### 1. **基础单文件打包（Windows GUI 程序）**
```bash
pyinstaller --onefile --windowed --icon=app.ico --add-data "assets/*;assets" app.py
```

#### 2. **处理隐藏导入和依赖路径**
```bash
pyinstaller --hidden-import pandas --paths "./lib" --collect-data sklearn app.py
```

#### 3. **生成 macOS 应用包（.app）**
```bash
pyinstaller --windowed --name MyApp --icon=app.icns --osx-bundle-identifier com.example.myapp app.py
```

---

### **注意事项**
1. **路径分隔符**  
   - Windows 使用 `分号 (;)` 分隔路径（如 `--add-data "src/*.txt;data"`）。
   - Linux/macOS 使用 `冒号 (:)`（如 `--add-data "src/*.txt:data"`）。

2. **依赖文件缺失**  
   若打包后程序运行报错，检查是否遗漏了：
   - 数据文件（通过 `--add-data` 添加）。
   - 隐式导入的模块（通过 `--hidden-import` 添加）。

3. **测试环境**  
   建议在干净的虚拟环境中打包，避免引入无关依赖。

4. **反编译风险**  
   `--key` 参数仅对字节码进行简单加密，无法完全防止反编译。

---

通过合理使用这些参数，可以解决 90% 的打包问题。如果遇到特殊需求，可以进一步修改生成的 `.spec` 文件进行高级配置。