# Python 格式化工具

URL: https://discuvr.org/python-formatter/?hl=zh-hant
Last updated: 2026-11-07
MCP tool: `format_python`

貼上 Python 程式碼，依你選擇的行寬與選項由 Black 進行格式化。語法錯誤會提供確切的行號。你的程式碼絕不會被執行，也絕不會被儲存。

這個工具會對你貼上的內容執行 Black - 多數 Python 專案早已認同的格式化工具 - 依你選擇的行寬與引號處理方式進行格式化。如果檔案無法解析，它會說明是哪一行；如果檔案已經格式化過，它也會照實告知，而不是假裝做了什麼。

## 功能作用

- 以 79、88、100 或 120 欄進行 Black 格式化。
- 「僅檢查」模式：在不修改檔案的情況下，了解檔案是否會改變。
- 保留你自己的引號風格，或讓 Black 統一規範它。
- 遵守或忽略那個讓集合保持展開狀態的神奇尾隨逗號。
- 當語法與版本相關時，指定目標 Python 版本。
- 語法錯誤會回報行號、欄號以及周圍的程式碼。
- 回報新增與刪除了多少行，以及檔案的整體結構。

## 運作方式

1. 貼上程式碼，或整個檔案的內容。
2. 選擇一個行寬以及你在意的任何選項。
3. 按下格式化，然後複製或下載結果。

## 你的程式碼永遠不會被執行

格式化 Python 程式碼並不需要執行它。程式碼會被解析成語法樹，再完全在記憶體中依據這棵樹重新寫出 - 它從不會被寫入檔案，從不會被匯入，也從不會被執行。一個會執行你貼上內容的格式化工具，其實就是帶著文字輸入框的遠端命令列。

## 為什麼是 Black，而不是我們自己的看法

Black 是一種保持 AST 不變的轉換：輸出的程式碼與輸入的程式碼是同一個程式。正是這個特性，才讓一個格式化工具值得信任，也正因如此，這個工具的任何環節都沒有語言模型參與其中。被要求整理程式碼的模型，偶爾會在整理過程中順手改寫某一行，而對可正常運作的程式碼進行無聲的改動，正是格式化工具絕不能犯的失誤。

## 僅檢查

這和 CI 問的是同一個問題：這個檔案會改變嗎？檢查模式會原樣傳回你的原始程式碼，並回報 Black 本來是否會重新格式化它，以及會改動多少行。這是快速弄清楚某個流水線為什麼在一個你無法在本地重現的檔案上失敗的辦法。

## 魔法結尾逗號與 fmt: off 實例

最後一項後面的逗號會讓 Black 把呼叫或集合保持為每行一項：result = compute(alpha, beta,) 會變成四行，alpha, 和 beta, 各佔一行。勾選忽略魔法結尾逗號後，同樣的輸入只要放得下行寬就會變成 result = compute(alpha, beta)。要保護手動對齊的程式碼區塊（例如矩陣），在它上方一行寫 # fmt: off，下方寫 # fmt: on，Black 會原樣保留兩者之間的內容；行尾的 # fmt: skip 只保護這一行。這些是 Black 本身的註解，所以在你專案的 CI 執行 Black 時同樣有效。

## 問題

**我的程式碼會被上傳或儲存嗎？**

程式碼會被送到伺服器，在記憶體中格式化後於同一個回應中傳回。沒有任何內容會被寫入磁碟、快取或記錄日誌，使用記錄只保留計數 - 大小、選項、改動了多少行 - 從不保留程式碼本身。

**格式化會改變我程式碼的行為嗎？**

不會。Black 改變的是排版，而不是行為，但它做的不只是挪動空格。它會刪除多餘的括號（x = (1) 變成 x = 1），把數字的前綴和指數改成小寫（0XABCDEF 變成 0xABCDEF，1E5 變成 1e5），把呼叫拆成多行時補上結尾逗號，壓縮連續的空行，並去掉 docstring 內部的空格（""" Doc. """ 變成 """Doc."""）。最後這一項會改變 __doc__ 的文字，只有當你的程式碼讀取自己的 docstring 時才有影響。

**為什麼它完全沒有重新格式化我的檔案？**

因為它在你選擇的行寬下已經是格式化過的了。工具會直接說「已經格式化過」，而不是悄悄傳回一份原樣副本。

**它會排序我的 import 嗎？**

不會。排序 import 是 isort 的工作，不是 Black 的，兩者分歧足夠常見，如果在這裡這麼做會讓你感到意外。

**它能格式化有語法錯誤的檔案嗎？**

任何格式化工具都做不到 - 一個無法解析的檔案沒有可供重寫的結構。你會得到行號、欄號以及周圍的程式碼，方便你修正後再試一次。

**它遵循 PEP 8 嗎？**

Black 與 PEP 8 相容，只有一處廣為人知的偏差：它的預設行寬是 88 而不是 79。如果你需要更嚴格的數值，請在行寬選擇器中選 79。

**最大能格式化多大的檔案？**

每次最多 400,000 個字元。格式化超過 10 秒會被中止，只有非常大或高度重複的檔案才會碰到，每個 IP 位址每 10 分鐘可格式化 30 次。

**如何在編輯器、pre-commit 或 CI 中得到同樣的格式？**

本頁執行的是 Black，寬螢幕時頁面頂端列會顯示其版本。Black 從 pyproject.toml 的 [tool.black] 區段讀取專案設定，鍵名與長命令列選項相同：你選的"行長度"對應 line-length = 88，勾選了"保留我的引號"就寫 skip-string-normalization = true，"忽略魔法結尾逗號"對應 skip-magic-trailing-comma = true，在"目標"中固定的版本對應 target-version = ["py311"]。編輯器外掛和 pre-commit 掛鉤讀取的也是這個檔案。用 black . 格式化，在 CI 中執行 black --check --diff . ：它不會修改任何檔案，若有檔案會被重新格式化則以結束代碼 1 結束。請固定與本頁相同的 Black 版本，因為每個日曆年的第一個版本可能會改變穩定風格。

**輸出結果與 Ruff 的格式化工具（ruff format）相同嗎？**

幾乎總是相同，但並非逐位元組一致。Ruff 的格式化工具被設計為 Black 的直接替代品，Ruff 文件指出，在 Django、Zulip 等已用 Black 格式化的大型專案上，超過 99.9% 的行結果完全相同。對從未經過 Black 處理的程式碼，差異會更多，尤其是行尾註解，其文件列出了刻意的差異。它的預設行長同樣是 88，在 [tool.ruff] 中以 line-length 設定；[tool.ruff.format] 中的 quote-style = "preserve" 對應"保留我的引號"，skip-magic-trailing-comma = true 對應"忽略魔法結尾逗號"。如果你的 CI 執行 ruff format --check，請用 Ruff 而不是本頁來檢查檔案。

## 更多開發者工具

- [HTML 檢視器](https://discuvr.org/html-viewer/?hl=zh-hant)
- [IP 子網路計算機](https://discuvr.org/ip-subnet-calculator/?hl=zh-hant)
- [編碼 / 解碼](https://discuvr.org/encode-decode/?hl=zh-hant)
- [Unix 時間戳記轉換器](https://discuvr.org/timestamp-converter/?hl=zh-hant)

## 常一起使用

- [文字比較](https://discuvr.org/text-diff/?hl=zh-hant)
- [大小寫轉換與行工具](https://discuvr.org/case-converter/?hl=zh-hant)
- [Study Buddy](https://discuvr.org/study-buddy/?hl=zh-hant)

---

Part of Discuvr (https://discuvr.org/): Discuvr is a collection of free, focused tools for day-to-day professional work - office and data utilities, legal and compliance helpers, privacy and security checks, and developer formatters. Every tool has its own page, and most can also be called from ChatGPT or Claude over MCP.