梳理 Python 代码格式化与静态检查工具：isort、Black、Flake8、Pylance、Ruff
Python 项目里”格式化工具""静态检查工具""类型检查工具”一大堆，光看名字很难分清各自负责什么。本文按照三个层次梳理最常见的 isort、Black、Flake8、Pylance、Ruff 这 5 个工具：①各自属于哪个类别 ②每个类别解决什么问题 ③实际项目里该怎么组合使用。
1. 先分清 3 个类别
Python 代码质量相关的工具，大体可以分为三类。
| 类别 | 解决的问题 | 会不会改代码 |
|---|---|---|
| 格式化工具（Formatter） | 按固定规则统一代码的外观（换行、缩进、引号、import 顺序等） | 会 |
| 静态检查工具（Linter） | 检测容易埋下 bug 的写法（未使用的 import、未定义变量、危险的比较等），只报警不修改 | 不会 |
| 类型检查工具（Type Checker） | 基于类型注解，在代码运行前发现类型不匹配 | 不会 |
把这 5 个工具对应到上面 3 个类别：
| 工具 | 所属类别 |
|---|---|
| isort | 格式化工具（专注 import 顺序） |
| Black | 格式化工具（整体代码风格） |
| Flake8 | 静态检查工具 |
| Pylance | 偏类型检查（编辑器语言服务器） |
| Ruff | 用一个工具重新实现格式化、静态检查这两大类的大部分能力 |
也就是说：isort 和 Black 属于”格式化工具”，Flake8 属于”静态检查工具”，Pylance 偏向”类型检查工具”，而 Ruff 并不局限于单一类别，而是横跨多个类别去替代它们。
2. 各工具具体做什么
格式化工具
isort —— 只做一件事：整理 import 语句的顺序。它会把标准库、第三方库、项目内模块分组，并在组内按字母顺序排列。isort 经常与 Black 搭配使用，早期的经典分工是”代码本身交给 Black，import 顺序交给 isort”。
Black —— 以”不容商量”（opinionated）著称的格式化工具，几乎没有可配置项，对换行、引号风格（默认双引号）、末尾逗号等给出唯一确定的格式化结果。它的设计目的就是终结团队内部关于代码风格的争论（用 Tab 还是空格、单引号还是双引号）。Black 只负责格式化，不检测 bug。
静态检查工具
Flake8 —— 检测 PEP8（代码规范）违规、未使用的 import/变量、复杂度过高的函数等问题的经典 linter。Flake8 本身只是一层很薄的封装，底层由 pyflakes（检测 bug）＋ pycodestyle（PEP8 检查）＋ mccabe（复杂度度量）组成。Flake8 本身不会修改代码（没有自动修复功能）。
类型检查工具
Pylance —— VS Code 的 Python 语言服务器，基于微软自研的类型检查器 Pyright。它在编辑器里实时提供代码补全、跳转到定义、类型不匹配检测、悬浮提示类型信息等功能。相比其他能在 CI 里跑的工具，Pylance 更偏向于支撑编辑器内的开发体验（DX）。
跨类别的整合型工具
Ruff —— 用 Rust 实现的高速静态检查与格式化工具，把 Flake8 本体、数十个 Flake8 插件、isort，以及部分 pyupgrade 的规则集，都用一个二进制文件重新实现了一遍。ruff check 提供相当于 Flake8 的静态检查，ruff format 提供与 Black 兼容的格式化，--fix 还能自动修复大部分问题。它最大的特点是把”格式化”和”静态检查”这两大类以极高的速度合并进一个工具（不涉及类型检查）。
3. 对比表
| 工具 | 类型 | 主要工作 | 自动修复 | 执行速度 | 类型检查 |
|---|---|---|---|---|---|
| isort | 格式化工具 | 整理 import 顺序 | 有 | 快 | 无 |
| Black | 格式化工具 | 整体代码格式化 | 有 | 一般 | 无 |
| Flake8 | 静态检查工具 | 检测 PEP8／疑似 bug | 无 | 一般 | 无 |
| Pylance | 语言服务器／类型检查器 | 编辑器补全与类型校验 | 部分（Quick Fix） | 快（常驻） | 有（Pyright） |
| Ruff | 静态检查＋格式化 | 高速替代 Flake8＋isort | 有 | 非常快 | 无 |
4. 该怎么组合使用
- 新项目想要最精简的配置 → 单用 Ruff（
ruff format+ruff check --fix）就能覆盖格式化、import 整理和大部分 Lint 规则，CI 和编辑器保存时用的是同一套规则。 - 老项目已经用 Black + isort + Flake8 搭好了 → 不必强行替换，用 Ruff 里兼容 Flake8/isort 的规则逐步迁移更稳妥（部分规则的行为存在细微差异）。
- 想加强类型安全 → Ruff 和 Flake8 都不做类型检查，需要额外搭配 Pylance（编辑器端）与
pyright/mypy（CI 端）。 - 目标是提升编辑器体验 → 和其他跑一次就结束的 CLI 工具不同，Pylance 常驻在编辑器里提供补全、跳转、悬浮提示，目的和 CI 里的 Lint 不一样。CI 里应单独接入 Ruff 或 mypy。
小结
截至 2026 年，“格式化与大部分 Lint 统一交给 Ruff""类型检查交给 Pylance（编辑器）＋ mypy/pyright（CI）“是一套简单且高速的标准组合。