Black 是目前 Python 社區(qū)最流行的自動格式化工具之一，它的特點是“極少配置、強(qiáng)制風(fēng)格”：你把代碼交給 Black，它按照一套統(tǒng)一規(guī)則幫你排版，從此團(tuán)隊不用再糾結(jié)“空格還是換行”。

一、Black 簡介

Black 的核心理念：

• 只做格式，不改語義。
• 盡量減少可配置項，以統(tǒng)一風(fēng)格。
• 通過命令行或編輯器擴(kuò)展自動格式化。

在 VS Code 中使用 Black 的典型流程是：

• 保存文件 → Black 自動修改代碼排版 → 你只關(guān)注業(yè)務(wù)邏輯。

二、安裝 Black

在 VS Code 中使用 Black，底層還是依賴系統(tǒng)/虛擬環(huán)境中的 black 命令。因此第一步是安裝 Black。

2.1 在項目虛擬環(huán)境中安裝（推薦）

# 創(chuàng)建虛擬環(huán)境（示例）
python -m venv .venv

# 激活虛擬環(huán)境（Windows）
.\.venv\Scripts\activate

# 激活虛擬環(huán)境（macOS / Linux）
source .venv/bin/activate

# 安裝 black
pip install black

這樣做的好處：

• 每個項目可以使用各自版本的 Black，避免項目之間互相影響。
• 便于在 requirements.txt 或 pyproject.toml 中記錄依賴版本。

2.2 全局安裝（不太推薦，但可以）

pip install --user black

適合個人簡單腳本項目，但團(tuán)隊協(xié)作時，還是建議使用虛擬環(huán)境或者在 pyproject.toml 中鎖定 Black 版本。

三、VS Code 基礎(chǔ)配置：啟用 Python 擴(kuò)展

在 VS Code 中使用 Black 之前，需要先裝好 Python 擴(kuò)展。

1. 打開 VS Code
2. 左側(cè)點擊「擴(kuò)展（Extensions）」圖標(biāo)
3. 搜索 Python，安裝 Microsoft 官方的 Python 擴(kuò)展
4. 推薦同時安裝 Pylance 擴(kuò)展（類型提示、補(bǔ)全更好）

安裝好后，VS Code 會自動識別 .py 文件的 Python 語言特性。

四、在 VS Code 中選擇解釋器（指向 Black 所在環(huán)境）

如果你把 Black 安裝在虛擬環(huán)境里，需要讓 VS Code 知道用哪個 Python 解釋器（也就是哪個虛擬環(huán)境）。

1. 打開 Python 項目
2. 按 Ctrl+Shift+P（macOS 上 Cmd+Shift+P）打開命令面板
3. 輸入并選擇：Python: Select Interpreter
4. 在列表中選擇你創(chuàng)建的虛擬環(huán)境，比如：
   • .venv
   • venv
   • 或其他你自定義的名字

選擇正確解釋器后：

• VS Code 使用該環(huán)境運行 Black、lint 工具、調(diào)試等。
• 若 Black 在此環(huán)境中安裝成功，后面配置就能正常工作。

五、將 Black 設(shè)置為默認(rèn)格式化工具

VS Code 支持多個格式化工具（如 autopep8、yapf、Black），需要顯式告訴 VS Code：Python 用 Black 來格式化。

5.1 通過設(shè)置圖形界面配置（適合初學(xué)）

1. 打開設(shè)置：
   • 方式一：左下角齒輪 → Settings
   • 方式二：快捷鍵 Ctrl+, / Cmd+,
2. 右上角搜索框中輸入：Python Formatting Provider
3. 在下拉選項中選擇：black

若搜索不到該選項，可以搜索 formatting provider 或換成中文關(guān)鍵字（如“格式化”），確保 Python 擴(kuò)展已安裝。

5.2 直接編輯settings.json（適合熟悉 VS Code 配置的人）

1. Ctrl+Shift+P / Cmd+Shift+P
2. 輸入：Preferences: Open Settings (JSON)
3. 在 JSON 中添加或修改如下內(nèi)容（注意逗號語法）：

{
    // ... 其他設(shè)置 ...

    // 使用 Black 作為 Python 格式化工具
    "python.formatting.provider": "black"
}

保存后生效。

六、啟用「保存時自動格式化」

為了真正“無感”使用 Black，建議開啟保存即自動格式化。

6.1 全局啟用保存自動格式化（所有語言）

1. 設(shè)置中搜索：Format On Save
2. 勾選：Editor: Format On Save（editor.formatOnSave）

這意味著所有支持格式化的文件在保存時都會被對應(yīng)的格式化工具處理。

6.2 只針對 Python 啟用（更精細(xì)控制）

如果只希望 Python 自動格式化，可以在 settings.json 中使用語言特定配置：

{
    // 全局不自動格式化
    "editor.formatOnSave": false,

    "[python]": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "ms-python.python"  // 使用 Python 擴(kuò)展的格式化
    },

    "python.formatting.provider": "black"
}

說明：

• "[python]" 里的配置只對 Python 文件生效。
• editor.defaultFormatter 指定該語言由哪個擴(kuò)展來執(zhí)行格式化，ms-python.python 是官方 Python 擴(kuò)展的 ID。

保存 settings.json 后，打開一個 .py 文件，試著寫點不規(guī)整的代碼，然后保存，看是否會被 Black 重新排版。

七、手動觸發(fā) Black 格式化

即使不開保存自動格式化，你也可以隨時手動觸發(fā)格式化：

• 快捷鍵：
  • Windows / Linux：Shift+Alt+F
  • macOS：Shift+Option+F
• 或右鍵代碼編輯區(qū) → 選擇「Format Document」

如果出現(xiàn)彈窗提示「選擇格式化程序」：

1. 選擇 Python 格式化（一般會有 Python 或 Black 等選項）
2. 如果沒看到 Black，需要確認(rèn)上面幾步是否已正確安裝 / 配置。

八、配置 Black 的行為（行寬等）

Black 的設(shè)計理念是“少配置”，但仍然提供了幾個核心參數(shù)，最常用的是 line-length（最大行寬）。

Black 支持以下配置文件之一：

• pyproject.toml（推薦，現(xiàn)代項目標(biāo)配）
• pyproject.toml 中 [tool.black] 段落

8.1 在pyproject.toml中配置 Black（推薦）

在項目根目錄創(chuàng)建或編輯 pyproject.toml：

[tool.black]
line-length = 100
target-version = ["py310"]
skip-string-normalization = true

常見選項說明：

• line-length：最大行寬，默認(rèn) 88，可改為如 100、120 等。
• target-version：目標(biāo) Python 版本，影響一些語法支持。
• skip-string-normalization：默認(rèn)為 false，Black 會統(tǒng)一把字符串引號改為雙引號。如果不想改引號，可以設(shè)為 true。

Black 在運行時會自動從當(dāng)前目錄向上查找 pyproject.toml 中的 [tool.black] 配置段。

8.2 不建議在 VS Code 里直接改 Black 命令參數(shù)

以前的 Python 擴(kuò)展支持通過 python.formatting.blackArgs 添加 Black 參數(shù)，例如：

"python.formatting.blackArgs": [
    "--line-length", "100"
]

在新版本中，更推薦通過 pyproject.toml 來管理 Black 的配置，實現(xiàn)“編輯器/CI 一致”，避免 VS Code 和命令行用到不同的格式規(guī)則。

九、在命令行與 VS Code 中保持一致

如果你在 CI 或命令行也會運行 Black，強(qiáng)烈建議：

1. 在項目根目錄使用 pyproject.toml 統(tǒng)一配置 Black。
2. VS Code 只是調(diào)用安裝在虛擬環(huán)境里的那個 Black，可自動讀取同一份配置。

命令行示例：

# 在項目根目錄
black .
# 或者只格式化某些目錄
black src tests

VS Code 保存時用的規(guī)則會和命令行一致。

十、常見問題與排錯

10.1 保存時沒有自動格式化

排查步驟：

1. 確認(rèn) Black 已安裝在當(dāng)前項目使用的解釋器中：

   which python  # 或 py -V 環(huán)境檢查
   python -m pip show black
   

2. 在 VS Code 中確認(rèn)已選擇正確解釋器（Python: Select Interpreter）。
3. 查看 settings.json 中：
   • "python.formatting.provider": "black" 是否正確。
   • editor.formatOnSave 或 [python].editor.formatOnSave 是否為 true。
4. 手動執(zhí)行「Format Document」，看看是否有錯誤提示。

10.2 VS Code 提示找不到 Black

• 檢查終端中是否能運行：

  black --version
  

• 如果在 VS Code 自帶的終端中運行找不到，但在系統(tǒng)終端中能找到，很可能是：
  • VS Code 當(dāng)前使用的解釋器不同；
  • 或 PATH 沒有指向 Black 安裝位置。
• 解決：
  • 重新選擇解釋器（Python: Select Interpreter），選中安裝了 Black 的那個環(huán)境。
  • 盡量使用項目內(nèi)虛擬環(huán)境，并在 VS Code 終端中激活它。

10.3 Black 修改了很多代碼，看不習(xí)慣

建議的過渡策略：

1. 先在一個小項目或新模塊上試用 Black，熟悉風(fēng)格。
2. 在老項目中，可以先對單個目錄或文件手動格式化，而不是一次性改全倉庫。
3. 團(tuán)隊協(xié)作建議一次性全局格式化并單獨提一個 PR，讓后續(xù)代碼評審不被大量“格式 diff”干擾。

十一、總結(jié)步驟速查

如果你只想快速配置好，可以按下面 checklist 操作：

1. 在項目虛擬環(huán)境中安裝 Black：

   python -m venv .venv
   source .venv/bin/activate  # 或?qū)?yīng)平臺命令
   pip install black
   

2. 打開 VS Code，選擇虛擬環(huán)境為 Python 解釋器（Python: Select Interpreter）。
3. 安裝 VS Code 的 Python 擴(kuò)展（ms-python.python）。
4. 在設(shè)置中選擇 Black 為格式化器：

   "python.formatting.provider": "black"
   

5. 啟用保存自動格式化（推薦）：

   "[python]": {
       "editor.formatOnSave": true,
       "editor.defaultFormatter": "ms-python.python"
   }
   

6. 在 pyproject.toml 中添加 Black 配置（可選但推薦）：

   [tool.black]
   line-length = 100
   target-version = ["py310"]
   

配置完成后，寫一段亂排版的 Python 代碼，按 Ctrl+S 保存，你就能看到 Black 自動把它“修理得整整齊齊”。

總結(jié)

到此這篇關(guān)于在VS Code中使用Black格式化Python代碼的文章就介紹到這了,更多相關(guān)VSCode Black格式化Python代碼內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評論