# ⚡ QPyPack 快速入门指南 (Quick Start Guide)

欢迎使用 **QPyPack**！本指南将带你在 3 分钟内掌握 QPyPack 的核心功能与打包流程，轻松将 Python 脚本转换为可独立运行的原生可执行程序 (`.exe` / macOS App / Linux 二进制)。

---

## 📥 第一步：安装与启动 QPyPack

你可以根据使用习惯选择以下任意一种方式启动 QPyPack：

### 方式 A：通过 `pip` 安装（推荐开发者使用）

在已配置 Python (>= 3.8) 的终端中执行：

```bash
# 安装 QPyPack
pip install qpypack

# 在命令行直接启动 GUI 界面
qpypack
```

### 方式 B：使用预编译独立免安装版（适合无 Python 环境用户）

前往 [GitHub Releases](https://github.com/Qwejay/QPyPack/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](README.md)。