【備忘録】FastAPI × Uvicorn（バックエンド）＋index.html（フロントエンド）を VS Code でデバッグする完全ガイド

この記事のゴール
VS Code だけで FastAPI × Uvicorn のバックエンドと、同じワークスペースに置いた index.html フロントエンドを動かしながら、async def chat() などのハンドラ内部をブレークポイントで追えるようにすること。
さらに重要なのは ── .vscode/launch.json は必ず “ワークスペース直下” に置く という点です。ここを間違えると VS Code が設定を読み込まず、デバッグが始まりません。

1. プロジェクトの最小構成
1. main.py（例）
2. index.html（超シンプル例）
2. VS Code で launch.json を作成
3. ブレークポイントを置く
4. デバッグ実行と確認
5. うまく止まらない場合
6. まとめ

1. プロジェクトの最小構成

bashCopyEdityour-project/
├─ main.py               # ← FastAPI アプリ本体
├─ index.html            # ← フロントエンド（静的配信でも OK）
└─ .vscode/
   └─ launch.json        # ← ★ここがワークスペース直下にあることが超重要

main.py（例）

pythonCopyEditfrom fastapi import FastAPI, Request, Response
from fastapi.responses import HTMLResponse, FileResponse
from pydantic import BaseModel
import pathlib

app = FastAPI()
BASE_DIR = pathlib.Path(__file__).parent

@app.get("/", response_class=HTMLResponse)
async def root():
    return FileResponse(BASE_DIR / "index.html")

class ChatReq(BaseModel):
    messages: list[dict]

@app.post("/chat")
async def chat(req: ChatReq):
    # ブレークポイントはここでどうぞ
    return {"reply": "Hello"}

index.html（超シンプル例）

htmlCopyEdit<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8" />
  <title>FastAPI Front</title>
</head>
<body>
  <button id="btn">Chat</button>
  <script>
    document.getElementById('btn').onclick = async () => {
      const res = await fetch('/chat', {
        method:'POST',
        headers:{'Content-Type':'application/json'},
        body: JSON.stringify({messages:[{role:'user', content:'こんにちは'}]})
      });
      console.log(await res.json());
    };
  </script>
</body>
</html>

2. VS Code で launch.json を作成

VS Code 左サイドバー「▶︎ 実行とデバッグ」を開く。
「launch.json を作成」→ Python を選択。
生成された .vscode/launch.json の configurations に下記を追加して保存。

launch.json：：動作確認済み
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug FastAPI",
            "type": "python",
            "request": "launch",
            "module": "uvicorn",
            "args": [
                "main:app",
                "--reload",
                "--port",
                "8000"
            ],
            "justMyCode": false,
            "env": {
                "PYTHONASYNCIODEBUG": "1"
            }
        }
    ]
}

ここ最重要！

① .vscode/launch.json は ワークスペース直下 に置いてください。
　your-project/.vscode/launch.json 以外の場所にあると VS Code は認識しません。

②main.app が下位フォルダにある場合、相対パス指定：Ex. “app.main:app”

3. ブレークポイントを置く

main.py の async def chat() 行頭に赤丸をクリック。
index.html 側は通常のブラウザ DevTools で OK。

4. デバッグ実行と確認

「実行とデバッグ」ドロップダウンから Debug FastAPI (uvicorn) を選択し ▶︎ を押す。
組み込みターミナルに Uvicorn が起動。http://localhost:8000/ へアクセス。
index.html の「Chat」ボタンを押すと /chat エンドポイントが呼ばれ、 VS Code がブレークポイントで停止。
F10 でステップ実行、ローカル変数をウォッチして処理フローを追跡。

5. うまく止まらない場合

症状	チェックポイント
ブレークしない	`"main:app"` のパスが正しいか、ブレークポイントが無効マークになっていないか
launch.json が読まれない	`.vscode` フォルダーがワークスペース直下か確認 / JSON 構文エラー
外部ファイルが更新されても反映されない	`--reload` 付け忘れを確認