M3b：進階探索（選修）¶

這是進階探索 — 不承諾時長、不承諾一定能成功

這個模組會碰到兩件事： 1. tkinter GUI — 加圖形介面（中等難度） 2. PyInstaller 打包成 .exe — 進階且有蠻多 Windows 環境地雷

心態建議： - 你不需要做完才能結業。M3a 跑完已經達成 quick win 目標 - 卡住的時候，跳過是完全 OK 的選擇 - 踩雷也是學習 — 你會學到「怎麼問 Claude 解決陌生錯誤」 - 沒時間就直接跳 M4

目標：把 M3a 的 CLI 工具升級成有 GUI、或打包成獨立 .exe。時長：不限

macOS 學員注意

本模組以 Windows 為主寫的（Windows 上的地雷比較多、需要詳細指引）。macOS 上做這些事也可以，但細節不同：

主題	Windows	macOS
tkinter	內建可用	多數 Python 內建可用；若 `import tkinter` 失敗，`brew install python-tk@3.13`
打包格式	`.exe`（單檔 portable）	Mach-O binary 或 `.app` bundle
防毒誤判	Windows Defender 常誤判	主要遇 Gatekeeper signing（會跳「無法開啟、未識別開發者」），不是病毒誤判
解 Gatekeeper	N/A	右鍵「打開」→ 「打開」確認；或 `xattr -dr com.apple.quarantine dist/app`

遇到 macOS 特有錯誤就整段貼給 Claude，請它換 macOS 對應做法。本頁的「卡住了？」表也適用 — Claude 會自動判斷你的 OS。

你可以選哪條路？¶

路徑	難度	估時	推薦給
A. tkinter GUI	🟡 中	30-60 min	想看到「視窗化」的學員
B. PyInstaller .exe	🔴 難	不限（可能 1-3h）	想做出可以給同事用的 .exe
A + B	🔴 難	不限	兩個都想要

建議：先做 A，看到視窗有成就感再考慮 B。

路徑 A：加 tkinter GUI¶

tkinter 是 Python 內建的 GUI 套件（不用 pip install）。長得陽春但跑得起來。

A1. 跟 Claude 說需求¶

你現在要做

在 todo-list/ 資料夾啟動 Claude Code（如果還沒）：

cd $HOME\Desktop\todo-list
claude

跟 Claude 說

我想幫這個 todo list 加一個 tkinter GUI。

需求： - 新檔案 gui.py（不要動 app.py，CLI 模式保留） - 一個視窗，包含： - 上方：輸入框 + 「新增」按鈕 - 中間：todo 列表（顯示 [x]/[ ] 標記 + 文字） - 下方：「標記完成」「刪除」按鈕（操作選中的項目） - 資料用同一個 todos.json（跟 CLI 共用） - 視窗關掉前要記得存檔

請寫 gui.py，並告訴我怎麼跑。

你應該看到

Claude 會： 1. 跳 Write tool 權限提示，要寫 gui.py → 選 Yes 2. 告訴你跑法：python gui.py

A2. 跑跑看¶

你現在要做

python gui.py

你應該看到

一個視窗跳出來，有輸入框、列表、按鈕。試著新增幾個 todo、勾完成、刪除。

tkinter Todo List GUI 視窗：輸入框、新增按鈕、項目列表、標記完成與刪除按鈕

卡住了？

症狀	怎麼問 Claude
`ModuleNotFoundError: No module named '_tkinter'`	「Python 沒有 tkinter，我是 Windows，怎麼裝？」（很可能要重灌 Python 並勾 tcl/tk 選項）
視窗開了但完全空白	「gui.py 的視窗打開但裡面什麼都沒有，幫我看 layout」
中文變方塊 / 亂碼	「tkinter 中文顯示成方塊，請設定字型」
視窗一閃就消失	「視窗開了就立刻關掉，請看是不是 mainloop 沒呼叫」

A3. 改造你的 GUI¶

跟 Claude 對話加你想要的東西：

你可以這樣問

「我想加深色模式切換，請幫我加」
「按 Enter 也要能新增 todo，不只是按按鈕」
「列表加捲軸，太多項目時可以滾」
「視窗大小固定 600x400 不能拉」

每改一個，跑一次確認。

路徑 B：用 PyInstaller 打包成 .exe¶

進入雷區前的心理建設

PyInstaller 在 Windows 上的常見地雷：

防毒軟體誤判 — 把你打包的 .exe 視為病毒、隔離掉
缺 DLL — 在你電腦跑得好好的，給別人就爆
路徑壞掉 — 程式找不到 todos.json，因為打包後 path 變了
檔案超大 — 一個 todo list 打包出來可能 30-50 MB

不是 Claude 笨。是 PyInstaller 跟 Windows 的歷史包袱問題。遇到地雷時，心情放鬆、看 Claude 怎麼解、學到什麼就賺到。

B1. 安裝 PyInstaller¶

你現在要做

pip install pyinstaller

你應該看到

最後一行：

Successfully installed pyinstaller-x.x.x ...

B2. 第一次打包（先看會發生什麼事）¶

你現在要做

在 todo-list/ 資料夾：

pyinstaller --onefile app.py

這會跑 30 秒到 2 分鐘，跳一堆訊息。

你應該看到

結束時類似：

...
INFO: Building EXE from EXE-00.toc completed successfully.

然後資料夾會多出： - build/（過程暫存） - dist/app.exe ← 這個就是打包好的執行檔 - app.spec（打包設定檔）

B3. 跑跑看 .exe¶

你現在要做

cd dist
.\app.exe add "從 exe 新增的測試"
.\app.exe list

你應該看到

跟用 python app.py 一樣的輸出。但這個 .exe 在沒裝 Python 的電腦也能跑。

卡住了？以下情境很常見，不要慌

情境 1：防毒軟體把 .exe 隔離¶

症狀：跑 .exe 直接被刪掉、或顯示「被 Windows Defender 封鎖」

Windows Defender SmartScreen 對話框：仍要執行 / 不要執行按鈕

怎麼問 Claude：

PyInstaller 打包的 .exe 被 Windows Defender 誤判為病毒，請問常見原因跟解法？

常見解法： - 加 Windows Defender 排除清單 - 用 --onedir 取代 --onefile（誤判率較低） - 把可執行檔簽章（這超出本訓練範圍）

情境 2：.exe 找不到 todos.json¶

症狀：跑 add 沒事，但 list 顯示空的；或者報「No such file or directory: todos.json」

原因：--onefile 打包後，程式的執行路徑跟原本不一樣，相對路徑壞了。

怎麼問 Claude：

我用 PyInstaller --onefile 打包，但程式找不到 todos.json，似乎是路徑問題。請幫我改 app.py，讓它無論在 Python 直接跑、還是打包成 .exe，都能正確找到 todos.json 的位置。

Claude 會教你用 sys._MEIPASS 或 os.path.dirname(sys.executable) 處理。

情境 3：.exe 一閃就退¶

症狀：雙擊 .exe，cmd 視窗閃一下就消失，看不到任何訊息。

原因：CLI 程式跑完就退出。要從 PowerShell 跑才看得到輸出。

解法：用 PowerShell（不是雙擊）跑 .exe。

B4. 打包加 GUI 版本（A + B）¶

如果你有做完路徑 A，可以打包 gui.py：

你現在要做

pyinstaller --onefile --windowed gui.py

--windowed 意思是「不要開命令提示字元視窗」（GUI 程式才要這樣）。

你應該看到

dist/gui.exe 雙擊應該直接開 GUI 視窗，不會有黑底 cmd 視窗。

M3b 完成檢查（不要求全部做完）¶

試過至少一條路徑（A 或 B）
至少看過一次「程式跑起來」的成功畫面
更重要：你體驗過「跟 Claude 一起 debug 陌生錯誤」的過程

寫給堅持完賽的學員¶

如果你 A、B 都做完了，下面是進階方向（不會在訓練裡教）：

方向	為什麼難
加雲端同步（Google Drive / Dropbox）	OAuth、API key 管理、token 過期處理
多裝置共用（自架小 server）	網路、防火牆、安全性
App 圖示 + 自訂安裝程式	PyInstaller 進階參數 + NSIS

這些都是「下一個 quick win」可以挑戰的方向。

← M3a ｜ M4 →