在 VS Code 中配置 Python 解釋器的環(huán)境變量，核心分兩類(lèi)場(chǎng)景：一是配置系統(tǒng)環(huán)境變量讓 VS Code 識(shí)別到 Python 解釋器（解決“找不到解釋器”問(wèn)題），二是在 VS Code 內(nèi)為 Python 運(yùn)行/調(diào)試配置自定義環(huán)境變量（比如 API 密鑰、路徑別名等）。以下是分場(chǎng)景的實(shí)操指南，覆蓋 Windows/macOS/Linux 全平臺(tái)。

一、先理清核心概念

• 系統(tǒng)級(jí)環(huán)境變量（PATH）：讓操作系統(tǒng)（及 VS Code）能找到 Python 解釋器的可執(zhí)行文件（如 python.exe/python3），是 VS Code 識(shí)別解釋器的基礎(chǔ)；
• 項(xiàng)目級(jí)自定義環(huán)境變量：僅作用于當(dāng)前 Python 項(xiàng)目，比如運(yùn)行代碼時(shí)需要的 API_KEY、DATABASE_URL，或臨時(shí)修改 PYTHONPATH（讓解釋器識(shí)別自定義模塊路徑）。

二、場(chǎng)景1：配置系統(tǒng)環(huán)境變量（讓VS Code找到Python解釋器）

如果 VS Code 的“選擇解釋器”列表為空，大概率是 Python 未加入系統(tǒng) PATH，需手動(dòng)配置：

1. Windows 系統(tǒng)

步驟1：找到 Python 安裝路徑

• 官網(wǎng)默認(rèn)安裝路徑：C:\Users\你的用戶名\AppData\Local\Programs\Python\Python311（311 是版本號(hào)）；
• 自定義安裝路徑：比如 D:\Python311；
• 關(guān)鍵：路徑需包含 python.exe，且要同時(shí)添加 Scripts 文件夾（如 C:\Users\你的用戶名\AppData\Local\Programs\Python\Python311\Scripts，pip 工具所在路徑）。

步驟2：配置系統(tǒng)環(huán)境變量

1. 右鍵「此電腦」→「屬性」→「高級(jí)系統(tǒng)設(shè)置」→「環(huán)境變量」；
2. 在「系統(tǒng)變量」中找到 Path，點(diǎn)擊「編輯」；
3. 點(diǎn)擊「新建」，粘貼 Python 安裝路徑（如 C:\Users\XXX\AppData\Local\Programs\Python\Python311）；
4. 再「新建」，粘貼 Scripts 路徑（如 C:\Users\XXX\AppData\Local\Programs\Python\Python311\Scripts）；
5. 點(diǎn)擊「確定」保存，關(guān)閉所有窗口。

步驟3：驗(yàn)證

• 打開(kāi)新的命令提示符（CMD），輸入 python --version，能顯示版本號(hào)即配置成功；
• 重啟 VS Code，再執(zhí)行「Python: 選擇解釋器」，就能看到對(duì)應(yīng)的解釋器了。

2. macOS/Linux 系統(tǒng)

步驟1：找到 Python 安裝路徑

• 系統(tǒng)自帶 Python：/usr/bin/python3；
• 官網(wǎng)安裝的 Python：/usr/local/bin/python3 或 ~/Library/Frameworks/Python.framework/Versions/3.11/bin/python3；
• 虛擬環(huán)境：~/項(xiàng)目名/.venv/bin/python3。

步驟2：配置環(huán)境變量（以 zsh 為例，bash 同理）

1. 打開(kāi)終端，編輯環(huán)境變量配置文件：

   # zsh（macOS 新版默認(rèn)）
   vi ~/.zshrc
   # bash
   vi ~/.bash_profile
   

2. 在文件末尾添加以下內(nèi)容（替換為你的 Python 路徑）：

   # 添加 Python 解釋器路徑
   export PATH="/usr/local/bin/python3:$PATH"
   # 若需自定義 PYTHONPATH（讓解釋器識(shí)別自定義模塊）
   export PYTHONPATH="/Users/你的用戶名/項(xiàng)目目錄:$PYTHONPATH"
   

3. 保存并生效配置：

   # zsh
   source ~/.zshrc
   # bash
   source ~/.bash_profile
   

步驟3：驗(yàn)證

終端輸入 python3 --version，顯示版本號(hào)即生效；重啟 VS Code 即可識(shí)別解釋器。

三、場(chǎng)景2：在VS Code中配置Python自定義環(huán)境變量（運(yùn)行/調(diào)試用）

這類(lèi)環(huán)境變量?jī)H作用于當(dāng)前項(xiàng)目，不會(huì)污染系統(tǒng)環(huán)境，推薦以下4種方式（按優(yōu)先級(jí)/易用性排序）：

方式1：.env 文件（推薦，項(xiàng)目級(jí)隔離）

VS Code 的 Python 官方插件會(huì)自動(dòng)識(shí)別項(xiàng)目根目錄的 .env 文件，無(wú)需額外配置，是最規(guī)范的方式。

1. 在項(xiàng)目根目錄新建 .env 文件（文件名固定，無(wú)前綴）；
2. 按 鍵=值 格式寫(xiě)入環(huán)境變量，示例：

   # .env 文件內(nèi)容
   API_KEY=123456789
   DATABASE_URL=mysql://root:123456@localhost/test
   # 配置 PYTHONPATH（解決“模塊找不到”問(wèn)題）
   PYTHONPATH=./src:./utils
   

3. 直接運(yùn)行/調(diào)試 Python 代碼，解釋器會(huì)自動(dòng)加載這些環(huán)境變量。

方式2：settings.json（項(xiàng)目/全局級(jí)配置）

適合配置全局生效的環(huán)境變量，或?yàn)?VS Code 終端默認(rèn)配置環(huán)境變量：

1. 打開(kāi) VS Code，按下 Ctrl+,（Windows）/Cmd+,（macOS）打開(kāi)設(shè)置；
2. 點(diǎn)擊右上角「打開(kāi)設(shè)置（JSON）」（{} 圖標(biāo)）；
3. 添加以下配置（按需修改）：

   {
       // 為 Python 運(yùn)行/調(diào)試配置環(huán)境變量
       "python.envFile": "${workspaceFolder}/.env", // 指定.env文件路徑（默認(rèn)已識(shí)別，可省略）
       // 為 VS Code 集成終端配置環(huán)境變量
       "terminal.integrated.env.windows": { // Windows 系統(tǒng)
           "API_KEY": "123456789",
           "PYTHONPATH": "${workspaceFolder}/src"
       },
       "terminal.integrated.env.osx": { // macOS 系統(tǒng)
           "API_KEY": "123456789",
           "PYTHONPATH": "${workspaceFolder}/src"
       },
       "terminal.integrated.env.linux": { // Linux 系統(tǒng)
           "API_KEY": "123456789",
           "PYTHONPATH": "${workspaceFolder}/src"
       }
   }
   

4. 保存后，重啟 VS Code 終端即可生效。

方式3：launch.json（調(diào)試時(shí)專(zhuān)用）

僅作用于調(diào)試場(chǎng)景（按 F5 啟動(dòng)調(diào)試），適合調(diào)試時(shí)臨時(shí)配置環(huán)境變量：

1. 打開(kāi)「運(yùn)行和調(diào)試」面板（Ctrl+Shift+D），點(diǎn)擊「創(chuàng)建 launch.json 文件」→ 選擇「Python 文件」；
2. 在生成的 launch.json 中添加 env 字段，示例：

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Python: 當(dāng)前文件",
               "type": "python",
               "request": "launch",
               "program": "${file}",
               "console": "integratedTerminal",
               // 配置調(diào)試時(shí)的環(huán)境變量
               "env": {
                   "API_KEY": "123456789",
                   "PYTHONPATH": "${workspaceFolder}/src"
               }
           }
       ]
   }
   

3. 按 F5 調(diào)試代碼，環(huán)境變量會(huì)自動(dòng)生效。

方式4：終端臨時(shí)配置（臨時(shí)生效）

適合一次性測(cè)試，關(guān)閉終端后失效：

• Windows 終端（CMD）：

  set API_KEY=123456789
  python test.py
  

• Windows PowerShell：

  $env:API_KEY="123456789"
  python test.py
  

• macOS/Linux 終端：

  export API_KEY=123456789
  python3 test.py
  

四、驗(yàn)證環(huán)境變量是否生效

新建 test_env.py 文件，運(yùn)行代碼查看是否能讀取到環(huán)境變量：

import os

# 讀取單個(gè)環(huán)境變量
api_key = os.getenv("API_KEY")
print("API_KEY:", api_key)

# 讀取 PYTHONPATH
python_path = os.getenv("PYTHONPATH")
print("PYTHONPATH:", python_path)

# 列出所有環(huán)境變量（可選）
# print(dict(os.environ))

運(yùn)行后能輸出 .env/settings.json 中配置的值，即說(shuō)明環(huán)境變量生效。

五、常見(jiàn)問(wèn)題解決

1. .env 文件配置不生效

• 確認(rèn) .env 文件在項(xiàng)目根目錄（VS Code 打開(kāi)的文件夾根目錄）；
• 重啟 VS Code 的 Python 語(yǔ)言服務(wù)器：按下 Ctrl+Shift+P，輸入「Python: 重啟語(yǔ)言服務(wù)器」；
• 避免 .env 文件中有空格/注釋錯(cuò)誤（如 API_KEY = 123 帶空格會(huì)導(dǎo)致值包含空格，正確是 API_KEY=123）。

2. PYTHONPATH 配置后模塊仍找不到

• 確認(rèn) PYTHONPATH 路徑是絕對(duì)路徑，或相對(duì)于項(xiàng)目根目錄（如 ./src）；
• 運(yùn)行代碼前重啟 VS Code 終端（舊終端不會(huì)加載新的環(huán)境變量）；
• 在代碼開(kāi)頭手動(dòng)添加路徑（兜底方案）：

  import sys
  sys.path.append("./src") # 添加自定義模塊路徑
  

3. 系統(tǒng)環(huán)境變量配置后 VS Code 仍找不到解釋器

• 重啟 VS Code（甚至重啟電腦），確保環(huán)境變量生效；
• 手動(dòng)指定解釋器路徑：執(zhí)行「Python: 選擇解釋器」→「輸入解釋器路徑」→ 瀏覽到 python.exe/python3 所在路徑。

總結(jié)

• 若解決“VS Code 找不到 Python 解釋器”：配置系統(tǒng) PATH 環(huán)境變量；
• 若為項(xiàng)目配置自定義環(huán)境變量（如 API 密鑰、模塊路徑）：優(yōu)先用 .env 文件（隔離、易管理），調(diào)試專(zhuān)用則改 launch.json；
• 所有環(huán)境變量配置后，重啟 VS Code/終端是關(guān)鍵（避免舊環(huán)境未刷新）。