VS Code Debug launch.json 設定技巧

VS Code Debug 模式下 launch.json 的正確設定方式，解決 .env 無法載入、模組找不到等問題。

在 VS Code 使用 Debug 模式啟動前後端分離專案時，若專案目錄與 .vscode/launch.json 不在同一層，常會遇到 Debug 可啟動但 .env 無法載入、模組找不到等問題。本篇整理實務中最穩定的設定方式，適合直接套用於個人或團隊專案。

在 VS Code 使用 Debug 模式啟動後端專案時，常見遇到以下狀況：

後端專案資料夾與 .vscode/launch.json 不在同一層

Debug 可以啟動，但出現：

• 無法 import module
• .env 沒有成功載入
• 環境變數讀取失敗（如 os.getenv、BaseSettings 等）

專案結構範例

workspace-root/
├─ backend/
│  ├─ app/
│  │  ├─ __init__.py
│  │  └─ main.py
│  ├─ .env
│  └─ venv/
└─ .vscode/
   └─ launch.json

launch.json 正確設定（核心解法）

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "FastAPI Debug",
      "type": "python",
      "request": "launch",
      "module": "uvicorn",
      "cwd": "${workspaceFolder}/backend",
      "envFile": "${workspaceFolder}/backend/.env",
      "args": [
        "app.main:app",
        "--reload"
      ],
      "jinja": true
    }
  ]
}