PyQt学习系列笔记（Python Qt框架）

第九课：PyQt的应用程序打包与部署

---

课程目标

1. 掌握使用 PyInstaller 将PyQt应用程序打包为独立可执行文件
2. 学习处理 资源文件（图标、样式表、图片）和 依赖项
3. 实现 跨平台部署（Windows/macOS/Linux）
4. 了解 pyqtdeploy 工具的使用（高级打包方案）
5. 解决常见问题（如缺少依赖、资源加载失败）

---

一、打包工具简介

1.1 PyInstaller

• 优点：简单易用，支持单文件/多文件模式，自动识别依赖项。
• 缺点：生成的文件体积较大，调试需查看日志。

1.2 pyqtdeploy

• 优点：专为Qt应用设计，支持多平台打包（Windows/macOS/Linux/iOS/Android）。
• 缺点：配置复杂，需手动处理依赖项。

---

二、使用PyInstaller打包PyQt应用

2.1 安装PyInstaller

pip install pyinstaller

---

2.2 基础打包命令

# 单文件模式（推荐）
pyinstaller -F -w your_app.py

# 多文件模式（调试推荐）
pyinstaller -w your_app.py

• 参数说明：
  • -F：打包为单个可执行文件（onefile）
  • -w：隐藏控制台窗口（GUI程序专用）

---

2.3 处理资源文件

资源文件目录结构

your_project/
├── main.py               # 主程序
├── resources/
│   ├── icons/            # 图标文件
│   └── styles.qss        # 样式表
├── database/             # 数据库文件
└── images/               # 图片资源

修改资源路径

在代码中动态加载资源：

import sys
import os

def resource_path(relative_path):
    """获取资源文件的绝对路径（支持打包后运行）"""
    if hasattr(sys, '_MEIPASS'):
        return os.path.join(sys._MEIPASS, relative_path)
    return os.path.join(os.path.abspath("."), relative_path)

# 使用示例
icon_path = resource_path("resources/icons/app_icon.png")

---

2.4 修改spec文件（高级配置）

1. 生成spec文件：

   pyinstaller your_app.spec
   

2. 编辑spec文件：

   # 添加资源文件路径
   from PyInstaller.utils.hooks import collect_data_files
   datas = collect_data_files('your_project') + [('resources/*', 'resources/')]
   

3. 重新打包：

   pyinstaller your_app.spec
   

---

2.5 跨平台打包

• Windows：

  pyinstaller -F -w your_app.py
  

• Linux：

  pyinstaller -F -w your_app.py
  

• macOS：

  pyinstaller -F -w --osx-bundle-identifier=com.yourcompany.yourapp your_app.py
  

---

三、使用pyqtdeploy打包（高级）

3.1 安装pyqtdeploy

pip install pyqtdeploy

---

3.2 创建配置文件

pyqtdeploy-cli init -t app your_app

配置文件示例（your_app/pyqtdeploy.json）：

{
  "name": "your_app",
  "version": "1.0",
  "platforms": ["windows", "linux", "macos"],
  "sources": ["main.py"],
  "resources": ["resources/*"],
  "dependencies": ["PyQt5", "sqlite3"]
}

---

3.3 编译与打包

cd your_app
pyqtdeploy build

输出目录：

dist/
├── windows/
│   └── your_app.exe
├── linux/
│   └── your_app
└── macos/
    └── your_app.app

---

四、常见问题与解决方案

4.1 缺少依赖项

• 现象：运行时报错 ImportError: No module named ...
• 解决方法：
  1. 在spec文件中手动添加依赖：

     hiddenimports = ['your_missing_module']
     

  2. 使用 --hidden-import 参数：

     pyinstaller --hidden-import=your_missing_module your_app.py
     

---

4.2 资源文件无法加载

• 现象：运行时报错 FileNotFoundError: resources/icon.png
• 解决方法：
  1. 确保使用 resource_path() 函数处理路径。
  2. 在spec文件中添加资源文件：

     datas = [('resources/*', 'resources/')]
     

---

4.3 Linux/macOS运行失败

• 现象：打包后程序无法运行，提示缺少库文件
• 解决方法：
  1. 安装缺失的依赖：

     sudo apt-get install libgl1 libxext6  # Linux 示例
     

  2. 使用 ldd 检查依赖：

     ldd dist/your_app
     

---

五、进阶技巧

5.1 自定义图标

1. 准备 .ico 文件（Windows）或 .icns 文件（macOS）。
2. 在打包命令中添加图标参数：

   pyinstaller -F -w --icon=your_icon.ico your_app.py
   

---

5.2 自动更新机制

1. 使用第三方库（如 pyupdater）实现自动更新。
2. 打包时包含更新脚本：

   import pyupdater.client
   

---

5.3 分发策略

• Windows：使用 .exe 文件 + 安装包（Inno Setup）。
• Linux：提供 .tar.gz 或 .deb 包。
• macOS：提供 .dmg 或 .app 包。

---

六、总结与下一步

本节课重点讲解了：

1. PyInstaller 和 pyqtdeploy 的使用方法
2. 资源文件 和 依赖项 的处理技巧
3. 跨平台部署 的注意事项
4. 常见问题 的排查与解决

下节预告：
第十课将讲解PyQt的性能优化与调试技巧，包括内存泄漏检测、日志输出、性能分析工具的使用等！