2. 在 Visual Studio Code IDE 開發 Python 程式如何設定除錯

前言

在 VS Code 中開發 Python 時，除錯（Debug）主要依靠 launch.json 設定檔來控制執行環境與參數。

事前準備

請確保VS Code 已安裝以下擴充功能（Extensions）：

Python（由 Microsoft 提供）
Python Debugger（微軟官方的除錯引擎 debugpy）

設定除錯步驟

**1.步驟一：建立除錯設定檔 launch.json：**約 1 分鐘。

點擊左側邊欄的 Run and Debug 圖示（或按 Ctrl + Shift + D / Cmd + Shift + D）。

點擊 建立 launch.json 檔案。

環境選擇 Python Debugger，接著選擇 Python File。

4.VS Code 會自動在專案根目錄產生 .vscode/launch.json。

**2.步驟二：編寫範例 Python 程式碼：**測試用專案。

建立一個名為 app.py 的檔案，貼上以下包含變數檢視與函式調用的測試程式：

def calculate_discount(price, discount_rate):
    # 故意在這裡做計算
    final_price = price * (1 - discount_rate)
    return final_price
 
def main():
    user_name = "Alice"
    items = ["Book", "Pen", "Laptop"]
    original_price = 1000
    discount = 0.2
 
    print(f"Hello, {user_name}!")
    # 計算折扣價
    final_price = calculate_discount(original_price, discount)
 
    print(f"Original: ${original_price}, Final: ${final_price}")
 
if __name__ == "__main__":
    main()

3.步驟三：配置 launch.json

將 .vscode/launch.json 的內容替換為以下完整配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 偵測當前檔案",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": true
        },
        {
            "name": "Python: 指定檔名與帶入參數範例",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/app.py",
            "args": ["--env", "development"],
            "console": "integratedTerminal"
        }
    ]
}

**4.步驟四：打斷點並啟動除錯：**開始 Debug。

打開 app.py，在 第 14 行（final_price = calculate_discount(...)）左側行號旁點一下，會出現一個 紅色圓點（Breakpoint）。
按下 F5 或點擊左上角綠色 Play 按鈕。
程式會停在第 14 行，此時可以在左側變數視窗查看 user_name、items 等變數狀態。

常見控制面板操作快捷鍵

當程式停在斷點時，上方會跳出除錯工具列：

按鈕 / 動作	快捷鍵	功能說明
Continue (繼續)	`F5`	繼續執行程式，直到遇到下一個斷點
Step Over (單步跳過)	`F10`	執行目前這行，不進入函式內部
Step Into (單步進入)	`F11`	進入目前的函式內部（例如進入 `calculate_discount`）
Step Out (單步跳出)	`Shift + F11`	執行完當前函式並跳回上一層
Restart (重新開始)	`Ctrl + Shift + F5`	重新發起除錯 Session
Stop (停止)	`Shift + F5`	結束除錯模式

提示： 如果開發 Flask / Django 網頁或 FastApi，只需要在 launch.json 設定對應的啟動指令（例如指定 module 或 args），即可設定中斷點捕捉 HTTP 請求！

如何在 VS Code`launch.json`中為`Python`程式設定命令列參數 (`args`) 與環境變數 (`env`)？

在 VS Code 中，要在 launch.json 設定 命令列參數（args） 與 環境變數（env 或 envFile），只需要在對應的配置區塊中加入這些欄位即可。

以下為你整理最完整的實戰設定範例：

1.完整`launch.json` 設定範例

請將 .vscode/launch.json 替換或更新為以下內容：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 帶參數與環境變數除錯",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/main.py",
            "console": "integratedTerminal",
            "justMyCode": true,
            
            // 1. 設定命令列參數 (相當於在 Terminal 執行: python main.py --mode dev --limit 50 "hello world")
            "args": [
                "--mode", "dev",
                "--limit", "50",
                "hello world"
            ],
 
            // 2. 直接在設定檔中寫死環境變數
            "env": {
                "DATABASE_URL": "postgres://localhost:5432/mydb",
                "API_KEY": "xyz123_secret_key",
                "DEBUG_LEVEL": "INFO"
            },
 
            // 3. (可選) 載入外部的 .env 檔案 (若與 env 同時存在，以 env 優先)
            "envFile": "${workspaceFolder}/.env"
        }
    ]
}

2.欄位詳細說明與比對

① 命令列參數 (`args`)

格式：字串陣列 ["arg1", "arg2", ...]
運作機制：陣列中的每個元素會被當成一個獨立參數，自動傳遞給 Python 的 sys.argv 或 argparse / click / typer 解析器。
注意事項：如果是選項與值（如 --mode dev），請拆開成兩個字串 "--mode", "dev"，避免空格導致解析錯誤。

② 環境變數 (`env`)

格式：Key-Value 物件 {"KEY": "VALUE"}
運作機制：會在啟動 Python 時寫入 os.environ。
優點：非常適合測試特定環境配置（如切換 DB_HOST 或開啟 Debug 開關）。

③ 外部環境變數檔 (`envFile`)

格式：檔案路徑，例如 "${workspaceFolder}/.env"
內部內容範例（.env 檔）：
```
DB_PORT=5432
SECRET_TOKEN=my_jwt_secret
```
優點：可避免將敏感金鑰（如 API Key）寫死在團隊共用的 launch.json 內，記得將 .env 加到 .gitignore。

3.Python 驗證程式碼

你可以建立一個 main.py 來測試參數與環境變數是否有正確載入：

import sys
import os
 
def main():
    print("=== 1. 接收到的命令列參數 (sys.argv) ===")
    for index, arg in enumerate(sys.argv):
        print(f"  sys.argv[{index}] = {arg}")
 
    print("\n=== 2. 讀取到的環境變數 (os.environ) ===")
    print(f"  DATABASE_URL : {os.getenv('DATABASE_URL')}")
    print(f"  API_KEY      : {os.getenv('API_KEY')}")
    print(f"  DEBUG_LEVEL  : {os.getenv('DEBUG_LEVEL')}")
 
if __name__ == "__main__":
    main()

按下 F5 執行除錯後，在 Terminal 就會看到變數與參數都被順利帶入囉！

如何在 VS Code 中設定 launch.json 來除錯 FastAPI 或 Flask 應用程式？

除錯 (Debug) FastAPI 或 Flask 這類 Web 應用程式時，重點在於讓 VS Code 的 Debugger 啟動對應的伺服器（例如 Flask 的開發伺服器或 FastAPI 的 uvicorn），並開啟 熱重載 (Reload) 或 中斷點捕捉。

下面為你整理完整的 launch.json 設定與實戰做法：

1. 完整 `launch.json` 設定檔

請將 .vscode/launch.json 替換為以下配置（可同時包含 FastAPI 與 Flask，隨時切換）：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: FastAPI 應用程式",
            "type": "debugpy",
            "request": "launch",
            "module": "uvicorn",
            "args": [
                "main:app",         // 格式為：[檔名]:[FastAPI 實例名稱]
                "--reload",         // 存檔自動重載
                "--port", "8000",   // 指定 Port
                "--host", "127.0.0.1"
            ],
            "jinja": true,          // 支援 HTML 樣板除錯
            "justMyCode": true,     // 斷點只停在自己的程式碼，不跳進第三方套件
            "console": "integratedTerminal"
        },
        {
            "name": "Python: Flask 應用程式",
            "type": "debugpy",
            "request": "launch",
            "module": "flask",
            "env": {
                "FLASK_APP": "app.py",      // 指定 Entry Point 檔案
                "FLASK_ENV": "development", // 開啟開發模式 (支援熱重載)
                "FLASK_DEBUG": "1"
            },
            "args": [
                "run",
                "--no-debugger",            // 停用 Flask 內建除錯器，改用 VS Code 引擎
                "--no-reload"               // 建議關閉 Flask 內建 reload 避免二次派生 Process 導致斷點失效
            ],
            "jinja": true,
            "justMyCode": true,
            "console": "integratedTerminal"
        }
    ]
}

2. 實戰驗證範例

範例 A：FastAPI 驗證

建立 main.py：

from fastapi import FastAPI
 
app = FastAPI()
 
@app.get("/")
def read_root():
    user = "Alice"
    message = f"Hello, {user}!"  # 👈 在這行打斷點（Red Dot）
    return {"message": message}
 
@app.get("/items/{item_id}")
def read_item(item_id: int):
    result = item_id * 10       # 👈 在這行打斷點
    return {"item_id": item_id, "result": result}

除錯步驟：

切換至 VS Code 的 Run and Debug 面板 (Ctrl + Shift + D)。
上方下拉選單選擇 “Python: FastAPI 應用程式” 並按下 F5 啟動。
打開瀏覽器訪問 [http://127.0.0.1:8000/items/5](http://127.0.0.1:8000/items/5)。
VS Code 就會精準停在該 API 路由的斷點上，供你檢視 item_id 與區域變數！

範例 B：Flask 驗證

建立 app.py：

from flask import Flask, jsonify
 
app = Flask(__name__)
 
@app.route("/")
def hello_world():
    status = "success"
    data = {"project": "Flask Debug Demo"}  # 👈 在這行打斷點
    return jsonify(status=status, data=data)
 
if __name__ == "__main__":
    app.run()

除錯步驟：

在 Run and Debug 下拉選單選擇 “Python: Flask 應用程式” 並按 F5。
訪問 [http://127.0.0.1:5000/](http://127.0.0.1:5000/) 即可進入斷點。

3. 常見陷阱與排錯技巧

斷點沒停住 (Unverified Breakpoint)：
- 原因：Flask 的 --reload 或多進程 (Multi-process) 導致子進程沒有被 VS Code 的 Debugger 附加 (Attach)。
- 解法：在 Flask 的 args 加上 "--no-reload"，讓主進程由 VS Code 完整掌控。
網頁樣板無法偵錯：
- 解法：確認配置中有加入 "jinja": true，這樣在 .html 檔案裡的 Jinja2 語法上打斷點也能停住。

description	—
tags	python
date	2026-07-20

課程名稱： AI 與自動化與雲端服務

探索

2. 在 Visual Studio Code IDE 開發 Python 程式如何設定除錯

前言

事前準備

設定除錯步驟

常見控制面板操作快捷鍵

如何在 VS Code`launch.json`中為`Python`程式設定命令列參數 (`args`) 與環境變數 (`env`)？

1.完整`launch.json` 設定範例

2.欄位詳細說明與比對

① 命令列參數 (`args`)

② 環境變數 (`env`)

③ 外部環境變數檔 (`envFile`)

3.Python 驗證程式碼

如何在 VS Code 中設定 launch.json 來除錯 FastAPI 或 Flask 應用程式？

1. 完整 `launch.json` 設定檔

2. 實戰驗證範例

範例 A：FastAPI 驗證

範例 B：Flask 驗證

3. 常見陷阱與排錯技巧

相關主題與延伸閱讀

關係圖譜

目錄

反向連結

課程名稱： AI 與自動化與雲端服務

探索

2. 在 Visual Studio Code IDE 開發 Python 程式如何設定除錯

前言

事前準備

設定除錯步驟

常見控制面板操作快捷鍵

如何在 VS Codelaunch.json中為Python程式設定命令列參數 (args) 與環境變數 (env)？

1.完整launch.json 設定範例

2.欄位詳細說明與比對

① 命令列參數 (args)

② 環境變數 (env)

③ 外部環境變數檔 (envFile)

3.Python 驗證程式碼

如何在 VS Code 中設定 launch.json 來除錯 FastAPI 或 Flask 應用程式？

1. 完整 launch.json 設定檔

2. 實戰驗證範例

範例 A：FastAPI 驗證

範例 B：Flask 驗證

3. 常見陷阱與排錯技巧

相關主題與延伸閱讀

關係圖譜

目錄

反向連結

如何在 VS Code`launch.json`中為`Python`程式設定命令列參數 (`args`) 與環境變數 (`env`)？

1.完整`launch.json` 設定範例

① 命令列參數 (`args`)

② 環境變數 (`env`)

③ 外部環境變數檔 (`envFile`)

1. 完整 `launch.json` 設定檔