Python Debugpy
在 Python 程式碼需要互動式除錯時使用：隱藏的區域變數、令人困惑的狀態變更、失敗的測試、子程序、長時間運行的服務，或遠端/無頭(headless)附加。
選擇能夠到達問題幀(frame)的最小除錯器。
選擇
breakpoint()：本地程式碼，可編輯原始碼，最快路徑。python3 -m pdb：不需編輯原始碼，從頭啟動。python3 -m pdb -c continue：在未處理的例外處停止。debugpy：遠端/無頭進程、DAP 客戶端、已運行的 PID，或服務啟動時的競爭條件(race condition)。
指令
python3 -m pdb path/to/script.py arg1
python3 -m pdb -c continue path/to/script.py
python3 -c "import debugpy" || python3 -m pip install debugpy
python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client path/to/script.py
python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client -m package.module
python3 -m debugpy --listen 127.0.0.1:5678 --pid <pid>
對於原始碼編輯附加(attach)：
import debugpy
debugpy.listen(("127.0.0.1", 5678))
debugpy.wait_for_client()
debugpy.breakpoint()
對於事後檢驗(post-mortem)：
import pdb, sys
try:
run()
except Exception:
pdb.post_mortem(sys.exc_info()[2])
raise
pdb
- 流程：
n、s、r、c、q。 - 堆疊/原始碼：
w、u、d、a、l、ll。 - 變數值：
p expr、pp expr、display expr。 - 中斷點：
b file.py:42、b func、b file.py:42, condition、cl <num>。 - 變更/求值：
!statement；完整 REPL：interact。
規則
- 先用最小的指令或測試重現問題。
- 停用平行測試 worker 以使用 pdb；互動式 stdin 通常會在 worker pool 內中斷。
- 將
debugpy放在活躍的環境中；除非專案本身已經需要它，否則不要將其加入專案依賴。 - 將除錯伺服器綁定到
127.0.0.1；除非在隔離環境或隧道中，否則不要暴露0.0.0.0。 - 對並行工作階段(session)使用不同的通訊埠。
debugpy --pid會注入到正在運行的進程中；附加前請確認目標 PID。- 如果在 Linux 上 PID 附加失敗，請先檢查 ptrace/容器權限，再考慮變更目標。
- 提交前清理：
rg -n 'breakpoint\(|pdb\.set_trace|debugpy\.' --type py。 - 重新執行不含除錯器的正常專案測試/閘道(gate)。
PYTHONBREAKPOINT=0可停用breakpoint()。- 如果進程在除錯器分離(detach)後停住，請確認它並非仍暫停於中斷點上。