# QPyPack

---

現代化、開箱即用的跨平台 Python 應用程式打包 GUI 工具
_{基於 PyInstaller 與 Nuitka 雙引擎驅動，提供視覺化配置、靜態相依性分析與自動化建置工作流程}

## 📌 專案概述 **QPyPack** 是一款專為 Python 開發者打造的跨平台圖形化打包工具。透過深度整合 **PyInstaller**（直譯器與位元組碼打包）與 **Nuitka**（C/C++ 原生編譯）雙核心引擎，將繁瑣的底層編譯參數、隱式相依性分析、環境隔離與資源收集等流程轉化為直觀的可視化介面。無論是用於打包輕量命令列指令碼，還是包含大型複雜相依性（如 PySide6 / PyQt、Playwright、CustomTkinter、FastAPI 等）的桌面或伺服端應用，QPyPack 均可提供穩定、高成功率且可重現的建置體驗。 --- ## 📸 介面預覽 (Screenshots)

主介面（英文）主介面（中文）建置引擎與環境
相依性管理與掃描最佳化、簽名與安全關於與系統資訊

--- ## 🛠️ 核心架構與特性 ### 1. 雙建置引擎與精簡最佳化 * **雙引擎無縫切換**： * **PyInstaller**：建置速度快，零 C 編譯器相依，兼具優異的相容性與生態支援。 * **Nuitka**：將 Python 原始碼直接轉譯為 C/C++ 二進位檔，具備執行速度快、抗反編譯能力強、產物體積小等特點。 * **LTO 連結最佳化與模組修剪**：在精簡模式（Lite Mode）下支援開啟 `--lto=yes` 連結時間最佳化；針對 PySide/PyQt 自動識別並剔除未引用的重型子模組（如 WebEngine、3D、Quick 等），有效防止產物體積冗餘。 * **靈活產物形態**：支援 **單檔案 (`--onefile`)** 與 **目錄模式 (`--onedir`)**，支援自訂相依性內部存放目錄 (`--contents-directory`)。 ### 2. 靜態分析與相依性拓撲防護 * **原生 AST 遞迴掃描**：內建純 Python 實現的抽象語法樹（AST）靜態分析器，無需執行程式碼即可遞迴分析原始碼及專案目錄中的相依性匯入。 * **智慧套件名稱對應系統**：內建主流第三方函式庫匯入名稱與 PyPI 套件名稱對應表（如 `cv2` $\to$ `opencv-python`、`PIL` $\to$ `pillow`、`win32com` $\to$ `pywin32`），支援使用者自訂擴充。 * **廢棄相容套件動態隔離 (Backport Isolation)**：自動識別並屏蔽與目標 Python 版本內建模組衝突的過時 Backport 函式庫（如在 Python 3.10+ 下自動隔離 `pathlib`、`typing` 等），防止執行期引發不可預測的命名空間覆蓋。 ### 3. 環境自動化管理與容錯機制 * **C/C++ 編譯器自動託管**：自動偵測本機 MSVC、Clang (LLVM) 與 GCC 環境；在缺失本機編譯器時，Nuitka 引擎將自動下載並託管相容的 MinGW-w64 工具鏈。 * **環境生命週期管理**：支援獨立隔離虛擬環境與共享虛擬環境模式；支援對歷史失效虛擬環境的一鍵掃描與空間清理。 * **自適應資源與錯誤自癒**： * 建置前自動評估磁碟與實體記憶體，低記憶體狀態下自適應下調並行數（Adaptive Concurrency）。 * 自動攔截記憶體配置溢位（OOM / ZstdError）並自動降級為單執行緒低記憶體模式重試。 * 自動規避 Windows 防毒軟體對中繼圖示/暫存檔案的獨占鎖定。 ### 4. 程式碼簽名與交付保障 * **智慧數位簽名託管**：支援在 Windows 產物輸出後自動套用 Authenticode 數位簽名（相容 Signtool 與 PowerShell 引擎，整合 RFC 3161 時間戳記服務）；支援 macOS 下的一鍵 `codesign` 程式碼簽名。 * **自簽名憑證套件**：內建 Windows 自簽名程式碼簽名憑證（`.pfx`）產生工具，支援商業私密金鑰憑證與密碼配置。 * **專案配置預設匯入/匯出**：支援將所有建置參數、資源清單與對應規則匯出為獨立的 `.qpypack` 專案工程預設檔案，便於團隊共享與持續整合。 ### 5. 跨平台互動體驗 * **拖放即用**：直接拖入 Python 原始碼即可自動解析模組元資料（版本、作者、應用程式名稱）、推導進入點並匹配同層資源圖示。 * **向量渲染與全球化 i18n**：全介面基於 Google Material SVG 向量圖示繪製，完美適配 4K/高解析度螢幕 DPI 縮放；內建涵蓋簡繁中文、英語、日語、韓語、德語、法語等 17 種語言的即時國際化系統。 --- ## 📊 引擎選型對比 (PyInstaller vs. Nuitka) | 評估維度 | PyInstaller | Nuitka | | :--- | :--- | :--- | | **打包原理** | 打包 Python 直譯器與位元組碼檔案 (`.pyc`) | 將 Python 程式碼編譯為原生 C/C++ 二進位檔案 | | **建置速度** | 極快（通常 10 ~ 60 秒） | 較慢（涉及 C++ 程式碼產生與編譯器最佳化） | | **C/C++ 編譯器相依** | 無需任何外部編譯器 | 相依 MSVC / GCC / Clang（支援自動託管下載） | | **程式碼保護等級** | 基礎（可透過反編譯工具還原原始碼邏輯） | 極高（原生機器碼，深層抗逆向分析） | | **產物執行效能** | 接近原生 Python 執行速度 | 啟動速度快，部分迴圈與計算密集型邏輯更優 | | **推薦適用場景** | 快速反覆運算測試、內部工具、複雜動態匯入專案 | 商業交付軟體、核心演算法保護、追求體積與啟動速度 | --- ## ⚡ 快速開始 (Quick Start) > 💡 **首次使用？** 建議查閱 3 分鐘 [**📖 快速入門指南 (QUICKSTART.md)**](../../QUICKSTART.md) 了解詳細的使用教學與典型情境配置指南。 ### 安裝方式 1：透過 pip / pipx 安裝（推薦）在 Python >= 3.8 的環境中執行： ```bash # 透過 pip 安裝 pip install qpypack # 啟動圖形介面 qpypack ``` *若使用現代套件管理器（推薦）：* ```bash # 使用 pipx 隔離執行 pipx run qpypack # 或使用 uv 極速啟動 uvx qpypack ``` ### 安裝方式 2：使用獨立預編譯免安裝版無需預先安裝 Python 環境，可直接在 GitHub Release 頁面下載適用於您作業系統的可執行檔： 👉 [**下載預編譯版本 (GitHub Releases)**](https://github.com/Qwejay/QPyPack/releases) --- ## 📋 常用配置說明 ### 相依性與資源釋放路徑 (`sys._MEIPASS`) 在單檔案打包模式下，附加的資料檔案（圖片、配置、模型等）會在執行期暫時解壓縮至特定沙盒目錄。請確保在原始碼中按如下標準方式解析路徑： ```python import sys import os from pathlib import Path def get_asset_path(relative_path: str) -> Path: """取得打包後資源的絕對路徑""" if hasattr(sys, "_MEIPASS"): # PyInstaller 單檔案解壓縮目錄 base_path = Path(sys._MEIPASS) elif "__compiled__" in globals(): # Nuitka 二進位執行目錄 base_path = Path(sys.argv[0]).resolve().parent else: # 開發偵錯環境目錄 base_path = Path(__file__).resolve().parent return base_path / relative_path ``` --- ## 📅 版本更新歷史 (Changelog) 詳細的版本演進路線、功能新增與缺陷修復說明請參閱 [CHANGELOG.md](../../CHANGELOG.md)。 --- ## 💖 參與貢獻與贊助 (Sponsorship & Contributing) QPyPack 是一個遵循開源理念的專案。如果您在日常開發或工作中受益於本專案，歡迎透過以下方式支援本專案的長期維護與反覆運算： - 🌟 **Star 支援**：在 [GitHub](https://github.com/Qwejay/QPyPack) 上為專案點亮 Star。 - 🐛 **反饋與建議**：提交 [Issue](https://github.com/Qwejay/QPyPack/issues) 反饋缺陷或提出改進需求。 - ⚡ **贊助專案**：透過 [愛發電平台](https://www.ifdian.net/a/qwejay) 進行無償資助（支援微信 / 支付寶）。 > *註：贊助屬於對開源社群專案的無償鼓勵，不涉及任何商業承諾或客製化開發服務。感謝所有支援開源社群建設的開發者！* --- ## 📄 開源許可 (License) 本專案基於 [GNU General Public License v3.0 (GPL-3.0)](../../LICENSE) 協議開源。 > [!IMPORTANT] > **關於建置產物的版權說明**： > 使用 QPyPack 建置產生的最終應用程式與二進位產物，其**智慧財產權與開源授權完全由使用者自行決定**，QPyPack 的 GPL-3.0 許可協議不會對您的編譯產物施加傳染性約束。