在使用 Visual Studio Code (VS Code) 進行代碼調試時，launch.json 是一個非常關鍵的配置文件。它允許你定義多個調試任務，適用于不同的開發場景（如訓練腳本、Jupyter Notebook、單元測試等）。

本文將全面解析 launch.json 的結構、字段含義、可選參數、變量使用以及常見配置示例。

---

📦 一、基本結構

{"version": "0.2.0","configurations": [{// 每個配置項}]
}

• "version"：表示該文件的格式版本（通常為 "0.2.0"）。
• "configurations"：是一個數組，包含多個調試配置對象，每個對象對應一個調試任務。

---

🔍 二、單個配置項詳解

示例配置：

{"name": "Python: 調試訓練腳本","type": "debugpy","request": "launch","program": "${file}","console": "integratedTerminal","justMyCode": false,"args": ["--epochs", "10","--batch-size", "32"],"env": {"CUDA_VISIBLE_DEVICES": "0"},"envFile": "${workspaceFolder}/.env","stopOnEntry": false,"subProcess": true,"cwd": "${workspaceFolder}","debugOptions": ["RedirectOutput"]
}

---

🧩 三、字段說明與可選值

字段名	類型	描述	可選值
"name"	string	顯示在調試器中的名稱	自定義
"type"	string	使用的調試器類型	"debugpy", "python", "pwa-node" 等
"request"	string	請求類型	"launch"（啟動程序）、"attach"（附加到進程）
"program"	string	主程序入口路徑（支持變量）	文件路徑，如當前文件 ${file}，以及特定${workspaceFolder}/train.py
"console"	string	控制臺輸出方式	"integratedTerminal"、"none"、"internalConsole"
"justMyCode"	boolean	是否只調試用戶代碼	true、false
"args"	array	向程序傳遞的命令行參數	多個字符串組成的數組
"env"	object	設置環境變量	鍵值對形式
"envFile"	string	加載 .env 文件	文件路徑
"stopOnEntry"	boolean	是否在入口暫停	true、false
"subProcess"	boolean	是否調試子進程	true、false
"cwd"	string	當前工作目錄	文件路徑
"module"	string	指定運行模塊（替代 program）	如 "pytest"、"unittest"
"debugOptions"	array	特殊調試選項	"RedirectOutput"、"DjangoDebugging"、"Gevent" 等

---

📁 四、常用變量（宏替換）

VS Code 支持一些預定義變量，用于動態構建路徑和內容：

變量名	含義
${workspaceFolder}	當前工作區根目錄
${workspaceFolder:name}	多根項目中指定名稱的根目錄
${file}	當前打開的文件路徑
${fileDir}	當前文件所在目錄
${fileBasenameNoExtension}	當前文件名（不含擴展名）
${env:VAR_NAME}	獲取系統環境變量，例如 ${env:HOME}

---

🛠? 五、常見配置實例

1?? 調試當前打開的 .py 文件

{"name": "Python: 調試當前文件","type": "python","request": "launch","program": "${file}","console": "integratedTerminal"
}

? 適用于快速調試任意 Python 文件，無需修改配置。

---

2?? 調試 Jupyter Notebook

{"name": "Python: 調試Jupyter Notebook","type": "python","request": "launch","program": "${file}","console": "integratedTerminal","justMyCode": false
}

? 支持 .ipynb 文件調試（需安裝 Jupyter 擴展）。

---

3?? 調試 Pytest 測試用例

{"name": "Python: 調試測試用例","type": "python","request": "launch","module": "pytest","args": ["-v", "${file}"],"justMyCode": false
}

? 以調試模式運行 pytest 單元測試，支持斷點調試。

---

4?? 調試深度學習訓練腳本（帶 GPU 和環境變量）

{"name": "Python: 調試訓練腳本","type": "debugpy","request": "launch","program": "${workspaceFolder}/train.py","console": "integratedTerminal","justMyCode": false,"args": ["--epochs", "10","--batch-size", "32"],"env": {"CUDA_VISIBLE_DEVICES": "0","PYTHONPATH": "${workspaceFolder}"},"envFile": "${workspaceFolder}/.env","subProcess": true,"cwd": "${workspaceFolder}"
}

? 適用于多進程、GPU 計算等復雜場景。

---

📝 六、.env 文件示例

如果你希望將敏感信息或大量環境變量放在外部文件中，可以創建 .env 文件：

CUDA_VISIBLE_DEVICES=0
PYTHONPATH=/home/user/project
API_KEY=my_secret_key

然后在 launch.json 中引用它：

"envFile": "${workspaceFolder}/.env"

---

🧪 七、如何創建和編輯 launch.json

步驟如下：

1. 打開你的項目文件夾。
2. 在 .vscode/ 目錄下創建或編輯 launch.json。
3. 將上述配置復制進去，并根據你的實際路徑、參數進行修改。
4. 在左側點擊“運行和調試”圖標，選擇對應的調試配置，點擊綠色 ?? 開始調試。

---

🧠 八、小貼士

• 虛擬環境支持：確保 VS Code 使用了正確的 Python 解釋器（右下角顯示）。
• 路徑變量：
  • ${workspaceFolder}：當前工作區根目錄。
  • ${file}：當前打開的文件。
• 調試 Django 項目：啟用 "DjangoDebugging" 可獲得更好的兼容性。
• 多配置共存：你可以同時配置多個任務（如訓練、測試、Jupyter 調試），方便切換。

---

📚 九、參考文獻

• VS Code Debugging 官方文檔
• Python 調試官方文檔