4.5 KiB
4.5 KiB
⚡ QPyPack 快速入门指南 (Quick Start Guide)
欢迎使用 QPyPack！本指南将带你在 3 分钟内掌握 QPyPack 的核心功能与打包流程，轻松将 Python 脚本转换为可独立运行的原生可执行程序 (.exe / macOS App / Linux 二进制)。
📥 第一步：安装与启动 QPyPack
你可以根据使用习惯选择以下任意一种方式启动 QPyPack：
方式 A：通过 pip 安装（推荐开发者使用）
在已配置 Python (>= 3.8) 的终端中执行：
# 安装 QPyPack
pip install qpypack
# 在命令行直接启动 GUI 界面
qpypack
方式 B：使用预编译独立免安装版（适合无 Python 环境用户）
前往 GitHub Releases 下载对应系统的可执行文件：
- Windows: 下载
QPyPack.exe双击即可运行。 - macOS / Linux: 下载对应的预编译应用程序或可执行文件。
🎯 第二步：标准打包 5 步曲
启动 QPyPack 后，整体打包过程仅需简单点击几下：
[1. 拖入源码] ➔ [2. 选择引擎与模式] ➔ [3. 依赖与环境] ➔ [4. 点击构建] ➔ [5. 获取产物]
1. 拖入 Python 源码
- 将你的主入口文件（如
main.py或app.pyw）直接拖拽到主界面的虚线拖拽区域内。 - 软件将自动解析程序名称、自动比对脚本图标，并初始化工作空间。
2. 选择打包引擎与模式
切换到 「构建设置」 面板：
- 构建引擎 (Engine)：
- PyInstaller：打包速度极快，零配置，适合快速交付与常规应用。
- Nuitka：将 Python 编译为 C/C++ 二进制，体积更小、运行更快且具有极强的抗反编译保护（无需手动配置 C 编译器，QPyPack 会自动托管）。
- 打包模式 (Packaging Mode)：
- 单文件 (
--onefile)：生成单个.exe/ 可执行文件，干净便携。 - 精简模式 (Lite Mode)：动态排除开发/测试等冗余依赖，有效缩减产物体积（若失败可随时切回兼容模式）。
- 单文件 (
3. 配置 Python 环境与依赖
- Python 解释器：软件会自动检测系统默认 Python。若本地未安装 Python，可点击「查看 Python」一键自动下载并配置环境。
- 虚拟环境 (推荐勾选)：勾选「使用虚拟环境」可隔离本地污染；勾选「保留虚拟环境」可在多次重新打包时复用
.qpypack_venv，极大缩短后续构建时间。 - 依赖扫描：勾选「分析依赖 (原生 AST)」，QPyPack 会静态扫描源码中的隐式
import，彻底解决运行时ModuleNotFoundError。
4. 开始构建
- 点击底部的 「开始构建」 按钮。
- 可以在界面下方的 「执行日誌」 查看实时编译状态，支持切换「精简模式/详细模式」。
5. 获取打包产物
- 构建成功后，点击 「打开目录」 即可直接跳转到生成的应用程序目录。
💡 典型应用场景配置推荐
| 场景需求 | 推荐引擎 | 打包模式 | 关键设置 |
|---|---|---|---|
| 日常小工具 / 快速脚本 | PyInstaller | 单文件 (--onefile) + 精简模式 |
自动提取图标 |
| 商业软件 / 防反编译源码 | Nuitka | 单文件 (--onefile) + 兼容模式 |
使用虚拟环境 + 保留虚拟环境 |
| 大型 GUI 框架 (PySide/PyQt) | PyInstaller / Nuitka | 文件夹 (--onedir) |
勾选「分析依赖 (原生 AST)」 |
| Playwright / 爬虫自动化 | PyInstaller | 单文件 (--onefile) |
自动拦截 Playwright 浏览器依赖 |
❓ 常见问题排查 (FAQ)
Q1: 打包完成后运行报错 ModuleNotFoundError？
- 解决方法：前往【构建设置】->【依赖管理】，勾选 「分析依赖 (原生 AST)」 或 「扫描整个文件夹」；也可在「隐式导入 (hidden-imports)」中手动填入缺失的包名（如
pandas, PIL）。
Q2: 精简模式 (Lite Mode) 构建失败怎么办？
- 解决方法：精简模式会剔除不常用的动态依赖。如果构建失败，请在【构建设置】中将打包模式切回 「兼容模式 (Compatibility Mode)」 重新构建即可。
Q3: 使用 Nuitka 引擎提示缺少 C 编译器？
- 解决方法：不用担心！QPyPack 内置编译器智能托管，未检测到 MSVC 或 GCC 时会自动为你下载并配置 MinGW-w64 编译器工具链，全程无需手动干预。
📖 需要更详细的配置与高级优化说明？ 请参阅完整版 README.md。