前言

一篇掌握 PyInstaller：從零到可分發(fā)的 .exe。覆蓋安裝、常用參數(shù)、資源文件、GUI、.spec 進階、簽名與排錯。

為什么選擇 PyInstaller

適用：將 Python 腳本打包為無需 Python 環(huán)境的可執(zhí)行文件。

優(yōu)勢：自動分析依賴、跨平臺（需在目標平臺上構建）、支持單文件/目錄兩種分發(fā)方式。

工作原理快覽

解析入口腳本的導入依賴，收集 .py、數(shù)據(jù)文件、動態(tài)庫。

生成引導器（bootloader）+ 內(nèi)置 Python 解釋器 + 資源包。

--onefile：運行時臨時解壓到緩存目錄再執(zhí)行；--onedir：直接從目錄運行。

環(huán)境準備（建議使用虛擬環(huán)境）

# 1) 新建并激活 venv（PowerShell）
python -m venv .venv
.\.venv\Scripts\Activate.ps1
# 2) 升級基本工具
pip install -U pip wheel
# 3) 安裝 PyInstaller
pip install -U pyinstaller

快速入門（命令行應用）

示例 app.py：

# app.py
import sys, json
from pathlib import Path

def resource_path(relative):
    base = getattr(sys, "_MEIPASS", Path(__file__).parent)  # onefile 下的臨時目錄
    return Path(base) / relative

def main():
    print("Hello PyInstaller!")
    cfg = json.loads(resource_path("data/config.json").read_text(encoding="utf-8"))
    print("config:", cfg)

if __name__ == "__main__":
    main()

準備數(shù)據(jù)文件：data/config.json

{"app_name":"Hello","debug":true}

打包（單文件）：

pyinstaller -F -n hello `
  --add-data "data\config.json;data" `
  app.py

• Windows 的 --add-data 使用分號 ;（Linux/macOS 用冒號 :）。
• 輸出目錄：dist/hello.exe（成品）、build/（臨時）、hello.spec（構建配置）。

GUI 應用打包（隱藏控制臺）

• 控制臺程序（默認）：--console
• GUI 程序（隱藏控制臺）：-w 或 --windowed

pyinstaller -F -w -n MyApp -i assets\app.ico app.py

資源與路徑處理

讀取資源時使用上方 resource_path()，兼容開發(fā)與打包。

復制資源：

• 數(shù)據(jù)：--add-data "src_path;dest_dir"
• 二進制：--add-binary "src_path;dest_dir"

示例：

pyinstaller -F `
  --add-data "assets\logo.png;assets" `
  --add-binary "bin\helper.dll;bin" `
  app.py

依賴與導入問題

隱式導入未被自動檢測：--hidden-import some_pkg.submod

添加搜索路徑（非標準包位置）：--paths path\to\libs

縮小體積（排除不需要的模塊）：--exclude-module tests

常用模式與建議

--onefile：易分發(fā)；啟動需解壓，體積更大。

--onedir：啟動快；以文件夾分發(fā)，便于增量更新。

科學計算（numpy/pandas/scipy）通常推薦 --onedir 以提升啟動速度。

.spec 文件進階（可定制構建）

• 首次打包會生成 your_app.spec，可編輯以添加資源、修改參數(shù)。
• 使用 .spec 構建：pyinstaller your_app.spec
• 簡例（核心片段，實際文件更長）：

# hello.spec（示意）
datas = [("data\\config.json", "data"), ("assets\\logo.png", "assets")]
# 在 Analysis(...) 中傳入 datas；在 EXE(...) 中設置 name、icon、console 等

適合復雜資源收集、多個入口腳本、精細控制壓縮/排除。

圖標與版本信息（Windows）

圖標：-i path\to\icon.ico

版本資源：--version-file version_info.txt

version_info.txt 示例（節(jié)選）：

VSVersionInfo(
  FileVersion='1.0.0.0',
  ProductVersion='1.0.0.0',
  FileDescription='MyApp',
  CompanyName='Your Company',
)

代碼簽名與可信度（Windows）

• 未簽名的可執(zhí)行文件更易被殺毒攔截。
• 使用證書簽名（Windows SDK 的 signtool）：

signtool sign /a /fd sha256 /tr http://timestamp.digicert.com /td sha256 `
  dist\MyApp.exe

常見錯誤排查

“failed to execute script”：從命令行運行 dist\xxx.exe 觀察錯誤；嘗試 --log-level DEBUG。

啟動緩慢（單文件）：改用 --onedir 或減少資源體積；可選安裝 UPX 壓縮（可能觸發(fā)殺毒）。

缺少 DLL：確認依賴是否在同目錄或通過 --add-binary 復制；必要時在代碼中用 os.add_dll_directory() 設置路徑（Python 3.8+）。

打包前清理緩存：pyinstaller --clean -F app.py

構建與發(fā)布建議

固定依賴版本：requirements.txt；在干凈環(huán)境重裝后再打包。

在目標平臺上構建（Windows 打包 Windows，macOS 打包 macOS）。

小步驗證：先 --onedir 驗證，再切換 --onefile。

CI/CD：在流水線中使用同樣的命令和固定版本以保證可重復。

常用命令速查

# 單文件（控制臺）
pyinstaller -F -n app app.py
# 單文件（GUI，無控制臺）
pyinstaller -F -w -n app -i assets\app.ico app.py
# 追加資源/二進制
pyinstaller -F --add-data "data\cfg.json;data" --add-binary "bin\x.dll;bin" app.py
# 指定隱藏導入與路徑
pyinstaller -F --hidden-import pkg.sub --paths extra\libs app.py
# 清理并覆蓋輸出
pyinstaller --clean --noconfirm -F app.py
# 使用 spec 構建
pyinstaller app.spec

到此這篇關于Windows下PyInstaller打包Python的完整教程的文章就介紹到這了,更多相關PyInstaller打包Python內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！