目錄
1. 問題原因分析
2. 解決思路
3. 解決步驟
3.1 打開或創建 .vscode/launch.json
3.2 添加調試配置
3.3 配置說明
3.4 運行測試
4. 總結
在使用 VSCode 調試 Python 項目時，我們經常會遇到類似下面的錯誤：
Exception has occurred: ModuleNotFoundError
No module named 'open_webui'File "D:\extracodes\open-webui\backend\open_webui\main.py", line 51, in <module>from open_webui.utils import logger
ModuleNotFoundError: No module named 'open_webui'
這類問題的本質是 Python 模塊搜索路徑（sys.path）中沒有包含你的項目源碼目錄。
如果項目目錄結構不是純頂層包（例如 backend/open_webui），直接運行會找不到模塊。
1. 問題原因分析
Python 在導入模塊時，會從以下位置按順序查找：
-
當前運行文件所在目錄
-
環境變量
PYTHONPATH中指定的目錄 -
標準庫路徑
-
已安裝的第三方包路徑（
site-packages）
當你在 VSCode 中直接運行 main.py 時，當前工作目錄（cwd）默認為打開的文件所在目錄，而不是 backend。
這樣 open_webui 這個包就找不到了。
2. 解決思路
有三種常見方法可以解決這個問題：
-
調整 VSCode 的工作目錄（
cwd） -
設置
PYTHONPATH環境變量 -
在代碼中動態修改
sys.path（臨時方案）
本次采用的是 方法 1 + 方法 2 結合，通過 VSCode launch.json 配置，一勞永逸。
3. 解決步驟
3.1 打開或創建 .vscode/launch.json
在 VSCode 項目根目錄下創建 .vscode 文件夾，并新建 launch.json 文件。
3.2 添加調試配置
將以下配置粘貼進去，并根據實際情況修改 program 路徑：
{"configurations": [{"name": "Python Debugger: Current File","type": "debugpy","request": "launch","console": "integratedTerminal",// 要運行的 Python 文件路徑"program": "${workspaceFolder}/backend/open_webui/main.py",// 設置工作目錄為 backend（很關鍵）"cwd": "${workspaceFolder}/backend",// 設置 PYTHONPATH，讓 Python 能找到 open_webui 包"env": {"PYTHONPATH": "${workspaceFolder}/backend"}}]
}
3.3 配置說明
-
"program"：你要運行的 Python 主入口文件 -
"cwd"：調試運行時的工作目錄（當前工作路徑），這里必須指向backend -
"env"：額外設置環境變量，這里將PYTHONPATH指向backend，讓 Python 知道去這個目錄找包 -
"console": "integratedTerminal"：讓輸出顯示在 VSCode 內置終端中
3.4 運行測試
保存配置文件后：
-
在 VSCode 左側選擇 運行與調試 面板
-
選擇剛才創建的
"Python Debugger: Current File" -
點擊綠色運行按鈕或按 F5
此時程序會正常啟動，不再報 ModuleNotFoundError。
4. 總結
通過調整 VSCode 的 工作目錄（cwd） 和 PYTHONPATH 環境變量，我們可以解決大多數 包導入失敗 的問題。
優點：
-
不污染全局環境變量
-
不需要修改項目源碼
-
對整個項目的調試都有效
適用場景：
-
項目目錄不是純頂層包結構
-
想要在 VSCode 里一鍵運行而不是手動設置命令行路徑
💡 小貼士
如果你的項目有多個入口文件，可以在 launch.json 里配置多個 configurations，分別對應不同的啟動文件，這樣可以隨時切換運行目標。
)
