打包後在 Mac 上打不開，或啟動了卻找不到資料檔？ 最快解法：在 macOS 環境使用 PyInstaller 6.22.3 建置，先用目錄模式逐項驗證依賴與資源，再考慮單檔；打包成功不代表科研結果已可重現，也不代表應用已具備公開分發條件。PyInstaller 官方文件說明，跨作業系統建置需在對應平台建置。
這篇適合需要把 Python 分析程式交給 Mac 使用者的研究生或博士生。 也適合正在處理 GUI、資料檔或原生依賴的科研開發者。 若你負責課題組軟體交付，可直接參照下方流程制定可重複的建置與驗收紀錄。
先確認 PyInstaller 6.22.3 Mac 打包科研程式的交付目標
PyInstaller 的產物面向建置時所在的平台；在 Windows 上建立的執行檔不能直接當作 Mac 應用交付。若目標是 macOS，請在 macOS 環境建置，並核對實際使用的 Python、PyInstaller 版本、CPU 架構與原生依賴是否符合接收端環境。官方平台說明亦指出，跨平台分發需分別在對應平台建置。
截至 2026 年 10 月 21 日，PyInstaller 官方穩定版文件與變更紀錄列出 6.22.3；安裝前仍應以官方變更紀錄核對版本，避免照舊筆記安裝不同版本。這個版本資訊只確認 PyInstaller 發布狀態，不代表你的程式依賴或目標 Mac 已通過驗收。
| 交付情境 | 優先建置方式 | 主要驗收證據 | 建議評分 |
|---|---|---|---|
| 課題組內部驗收 | 先用目錄模式 | Finder 啟動、代表性輸入與輸出檔 | 高：方便逐檔檢查 |
| 交給合作者使用 | 先驗證目錄模式，再按安裝與更新方式決定封裝 | 對方帳戶能啟動，結果與原始程式一致 | 高：可追查資源缺漏 |
| 面向外部公開分發 | 建置與功能驗收完成後，再處理簽署及分發要求 | 簽署、必要的公證與目標使用情境檢查 | 中：多出發佈流程 |
動手前：複製專案並留下可重建的紀錄
先保留原始專案，另建一份可回退的建置副本。不要在唯一的工作目錄中直接升級依賴、修改啟動程式或加入打包設定；若建置後發生匯入錯誤，這樣才能區分原始程式問題與封裝變更。
準備副本時，整理一份建置紀錄，至少寫下 Python 版本、PyInstaller 版本、依賴清單、目標 Mac 架構，以及建置日期。這些欄位不是形式上的備註：缺少版本與架構資訊，其他研究者便難以判斷差異來自程式碼、依賴更新，還是建置環境。
接著清點程式執行所需的非程式碼資源，例如範例輸入、設定檔、分析模板、圖示與模型檔。資料目錄存在於原始專案，不等於它會自動進入應用產物；請另外標註哪些檔案必須隨應用提供，哪些應由使用者自行選取。
最後確認資料權限與使用邊界。先以不含個人資料、未公開研究資料或憑證的樣例驗證打包流程；若程式會讀取受限資料，需先確認資料能否複製到建置環境，以及建置日誌是否會記錄路徑或敏感資訊。
建置前的選擇：依照驗收需求決定交付形式
PyInstaller 支援目錄模式（onedir）與單檔模式（onefile）；官方文件列有兩種作業模式與相關命令選項。模式說明與命令選項文件應作為實際操作依據。首次打包科研程式，先選目錄模式，因為較容易檢查依賴、動態函式庫與資料檔是否進入產物。
| 條件分支 | 選擇 | 原因與回退方式 |
|---|---|---|
| 你需要逐項檢查依賴、定位缺檔，或仍在修正 GUI 與資料路徑 | 目錄模式 | 先保留可檢查的檔案結構；發現缺漏時回到建置設定補資源，再重新驗收 |
| 目錄模式已通過，接收者確實需要單一檔案交付，而且更新方式已確認 | 再評估單檔模式 | 單檔不是預設較佳；模式切換後，重新執行啟動、輸入輸出與路徑回歸檢查 |
| 資料會由使用者選取、更新，或需保存在可寫入位置 | 將資料與應用程式本體分開規劃 | 不要把會變動的資料當成只讀應用資源；若路徑規則尚未驗證，回到目錄模式 |
建置階段：從乾淨環境產生目錄模式應用
在 macOS 上建立專案副本的虛擬環境，安裝專案依賴，再安裝與建置紀錄一致的 PyInstaller 版本。以下命令以 PyInstaller 6.22.3 為例；版本依據可在官方變更紀錄核對：
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt
python3 -m pip install "PyInstaller==6.22.3"
python3 -m PyInstaller --onedir --windowed --name ResearchTool main.py把 requirements.txt、ResearchTool 與 main.py 替換為你的專案實際名稱；若專案沒有依賴清單，不要略過依賴紀錄，而應先整理並確認建置環境實際安裝的套件。--onedir 與 --windowed 等選項的含義及 macOS 使用方式，請對照官方命令選項文件。
建置後先檢查輸出目錄，不要只看終端機是否出現成功訊息。確認主要套件、動態函式庫，以及程式執行所需的範例設定和模板都已納入；對於動態匯入或套件資源，依錯誤訊息補上隱藏匯入或資料收集設定。PyInstaller 的 hook 機制文件說明了 hook 如何協助處理套件收集；資料檔與 spec 設定則可查閱官方 spec 文件。
若資料檔不在產物中，先確認它是應隨應用封裝，還是應由使用者選取。前者需要在打包設定中明確加入資源；後者則應由程式提供可辨識的選檔流程，並把結果寫到使用者有權限儲存的位置。PyInstaller 打包後找不到科研專案的資料檔怎麼辦？不要用硬編碼的開發機絕對路徑掩蓋問題，請先從專案副本重現缺檔，再檢查資源收集設定與執行時路徑解析。
首輪執行：從 Finder 驗證 GUI 與科研輸入輸出
命令列建置完成後，從 Finder 開啟產物，檢查視窗是否出現、按鈕與選單是否能操作、檔案選擇流程是否可用。從終端機啟動成功不代表 GUI 在一般使用情境也正確；記錄啟動方式、錯誤訊息與觸發步驟，方便其他人重現。
接著用已知輸入樣例，分別執行原始 Python 專案與打包應用。比較關鍵結果、輸出檔位置與日誌內容；如果輸出不同，先確認輸入檔、設定檔與依賴版本一致，再把封裝問題和分析邏輯問題分開定位。不要以「視窗能打開」作為科研程式驗收的結論。
檢查相對路徑時，留意目前工作目錄可能與開發環境不同。程式若預期在專案根目錄讀取資料，應改為明確定位應用資源，或讓使用者選取檔案；結果檔則應寫入使用者可存取的位置。每次修正路徑或資源設定後，都從乾淨副本重建並重做輸入輸出比對。
驗收階段：分清可啟動、可重現與可分發
PyInstaller 的 onedir 和 onefile 模式該怎麼選？除非目錄模式已通過檢查，而且單一檔案確實符合接收者的安裝與更新方式，否則先維持目錄模式。切換後重做 GUI 操作、代表性科研輸入、輸出位置與資料路徑檢查；封裝形式改變，不能沿用舊模式的驗收結論。
對課題組交付前，使用另一份專案副本或目標 Mac 帳戶進行複核。驗收紀錄應包含建置版本、輸入樣例識別方式、操作步驟、預期輸出與實際結果；若不能公開樣例，可在符合資料管理規範的前提下保留可稽核的檔案識別資訊與結果摘要。
打包的 Mac 應用需要簽署和公證嗎？這取決於應用的交付對象與分發方式；能在內部測試環境啟動，不代表已符合外部使用者的分發要求。簽署、公證與分發應依照 Apple 官方 macOS 軟體分發說明核對，不要嘗試繞過安全檢查。本文的功能驗收、科研結果重現與公開分發準備，是不同的驗收環節。
到此再依條件作出決定：
- 若應用只能在建置者帳戶啟動，先回到依賴、權限與路徑檢查，不要交付。
- 若應用能啟動，但代表性樣例的輸出尚未與原始程式核對，先補完科研結果驗收，不要宣稱可重現。
- 若功能與結果已驗收，但要交給外部使用者，依 Apple 當前官方要求處理簽署與分發，再作出公開發佈決定。
- 若課題組只在受控環境內使用，仍須按實際帳戶、資料管理規範與交付方式測試；內部使用不會自動替代功能驗收。