如何使用pyqtdeploy将PyQt应用打包为Windows、Android、iOS应用

一、前置准备 #

• 确认项目所有依赖可在目标平台运行，C扩展类库提前准备好对应平台的预编译静态版本
• 安装基础依赖：pip install pyqtdeploy pyqt5 sip，同时安装对应版本的Qt开发环境，确保qmake命令可全局调用
• 按目标平台提前装好对应开发环境：
  • Windows：装Visual Studio 2019/2022、对应架构的Qt for Windows、Windows SDK
  • Android：装Android NDK r25+、Android SDK、Qt for Android，配置好ANDROID_NDK_ROOT、ANDROID_SDK_ROOT环境变量
  • iOS：仅支持在MacOS上操作，装Xcode、Qt for iOS，配置好有效开发者签名

二、通用配置步骤 #

1. 生成项目配置文件：在项目根目录执行pyqtdeploy-cli --create myapp.pdt，生成后缀为pdt的pyqtdeploy专属配置文件
2. 可视化编辑配置：执行pyqtdeploy-gui myapp.pdt打开图形配置界面，核心配置项如下：

• 源文件路径：添加项目所有Python源文件、资源文件，排除__pycache__、虚拟环境等无用目录
• 依赖配置：逐个添加项目用到的第三方库，纯Python库可直接导入，C扩展库需关联提前编译好的静态库
• 入口配置：指定项目启动文件（如main.py）和入口函数
• Qt模块配置：仅勾选项目用到的Qt模块（如QtCore、QtGui、QtWidgets），多余模块不勾选可大幅减小包体积

3. 生成构建目录：配置完成后执行pyqtdeploy-cli --build myapp.pdt --target <目标平台>，目标平台可选值为windows/android/ios，执行后会生成对应平台的专属构建目录

三、各平台单独构建步骤 #

3.1 Windows平台 #

• 进入生成的构建目录，打开和Qt架构匹配的Visual Studio命令行工具
• 执行qmake生成Makefile
• 执行nmake编译，编译完成后在release目录可拿到独立exe文件，无需额外Python环境即可运行

3.2 Android平台 #

• 进入构建目录，执行qmake ANDROID_ABIS="armeabi-v7a arm64-v8a"，可根据需求调整要支持的ABI架构
• 执行make apk，编译完成后生成未签名apk安装包
• 使用自有签名文件对apk签名后即可安装到安卓设备或上架应用商店，不要使用默认测试签名

3.3 iOS平台 #

• 在MacOS系统下进入构建目录，执行qmake -spec macx-ios-clang CONFIG+=release CONFIG+=iphoneos
• 执行make编译，生成.xcodeproj项目文件
• 用Xcode打开该项目，配置好开发者账号签名，选择目标设备后即可运行调试或打包导出ipa文件，可用于TestFlight测试或上架App Store

常见问题排查 #

• 运行时提示缺模块：返回pdt配置检查是否漏加依赖，尤其是隐式导入的库
• 包体积过大：删除未用到的Qt模块、Python模块，Windows平台可使用upx对exe加壳压缩
• 移动端打包失败：检查NDK/Xcode版本是否和Qt版本匹配，Qt 5.15及以上版本才支持NDK r25，过新的NDK版本可能存在兼容问题

内容的提问来源于stack exchange，提问作者jett chen