Python Ruff — 代码检查与格式化
Ruff 是一个用 Rust 编写的极速 Python 代码检查器（linter）和代码格式化工具。它用一个统一的工具替代 Flake8、Black、isort、pydocstyle、pyupgrade 和 autoflake，运行速度比它们各自快 10–100 倍。Ruff 支持 800 多条内置规则，并对许多违规提供自动修复能力。
安装
可通过 pip、uv 安装，或作为开发依赖安装：
pip install ruff uv add --dev ruff
核心命令
ruff check # 检查当前目录下所有文件 ruff check --fix # 检查并自动修复安全违规 ruff check --unsafe-fixes # 显示不安全修复（应用前先审查） ruff check --fix --unsafe-fixes # 应用所有修复，包括不安全的 ruff check --watch # 文件变更时重新检查 ruff format # 格式化当前目录下所有文件 ruff format --check # 检查格式但不写入更改 ruff format --diff # 显示格式差异但不写入
按顺序同时运行检查（含导入排序）和格式化：
ruff check --select I --fix # 先排序导入 ruff format # 再格式化
配置
Ruff 从 pyproject.toml、ruff.toml 或 .ruff.toml 读取配置。三者支持相同的 schema；ruff.toml 和 .ruff.toml 省略 [tool.ruff] 前缀。
推荐的入门配置
[tool.ruff] target-version = "py312" line-length = 88
[tool.ruff.lint] select = [ "E", # pycodestyle errors "F", # Pyflakes "UP", # pyupgrade "B", # flake8-bugbear "SIM", # flake8-simplify "I", # isort ] ignore = ["E501"] # line-too-long（由格式化器处理）
[tool.ruff.format] quote-style = "double" indent-style = "space" docstring-code-format = true
完整配置参考见 references/configuration-guide.md。
规则选择最佳实践
规则代码遵循“前缀 + 数字”的模式（例如 F401 = Pyflakes 未使用导入，E711 = pycodestyle 与 None 比较）。
从小处开始，再逐步扩展：
第 1 步：最小（安全基线）
select = ["E4", "E7", "E9", "F"]
第 2 步：推荐扩展
select = ["E", "F", "UP", "B", "SIM", "I"]
第 3 步：严格（配合针对性忽略）
select = ["ALL"] ignore = ["D", "ANN", "COM812", "ISC001"]
关键规则前缀：
前缀 | 来源 | 用途 E/W | pycodestyle | 风格错误与警告 F | Pyflakes | 逻辑错误、未使用导入 B | flake8-bugbear | 可能的 bug 与设计问题 UP | pyupgrade | 升级到现代 Python 语法 SIM | flake8-simplify | 代码简化 I | isort | 导入排序 N | pep8-naming | 命名约定检查 D | pydocstyle | 文档字符串约定 ANN | flake8-annotations | 类型注解强制 S | flake8-bandit | 安全检查 RUF | Ruff-native | Ruff 特有规则
使用 lint.select（而非 lint.extend-select）让规则集显式化。避免在没有精心整理忽略列表的情况下启用 ALL，因为每次 Ruff 升级都会启用新规则。
详细规则指导与常见忽略见 references/rule-categories.md。
自动修复
Ruff 区分安全修复与不安全修复：
安全修复完全保持代码行为不变——默认通过 --fix 应用 不安全修复可能改变运行时行为（例如异常类型、移除注释）——需通过 --unsafe-fixes 显式启用
按规则提升或降低修复安全性：
[tool.ruff.lint] extend-safe-fixes = ["UP"] # 将 pyupgrade 修复视为安全 extend-unsafe-fixes = ["B"] # 要求对 bugbear 修复显式启用
禁用特定规则的自动修复，同时保留其为违规：
[tool.ruff.lint] fixable = ["ALL"] unfixable = ["F401"] # 标记未使用导入但不自动移除
错误抑制
行级抑制
import os # noqa: F401 x = 1 # noqa: E741, F841 # 抑制多条规则 y = 1 # noqa # 抑制全部（避免——过于宽泛）
块级抑制（优于笼统 noqa）
ruff: disable[E501]
LONG_CONSTANT_1 = "Lorem ipsum dolor sit amet, consectetur adipiscing..." LONG_CONSTANT_2 = "Lorem ipsum dolor sit amet, consectetur adipiscing..."
ruff: enable[E501]
文件级抑制
ruff: noqa: F841 # 对整个文件抑制特定规则
ruff: noqa # 抑制全部（避免——改用 per-file-ignores）
配置中的按文件忽略（首选）
[tool.ruff.lint.per-file-ignores] "init.py" = ["F401"] # 重新导出是有意为之 "tests//*.py" = ["S101", "ANN"] # 测试中允许 assert 且无需注解 "scripts//*.py" = ["T20"] # 脚本中允许 print()
检测未使用的抑制
ruff check --extend-select RUF100 # 标记过期的 noqa 注释 ruff check --extend-select RUF100 --fix # 自动移除过期 noqa
格式化器配置
Ruff 格式化器是 Black 的直接替代品。关键选项：
[tool.ruff.format] quote-style = "double" # "double" | "single" | "preserve" indent-style = "space" # "space" | "tab" line-ending = "auto" # "auto" | "lf" | "crlf" | "native" skip-magic-trailing-comma = false # 尊重尾随逗号（类似 Black） docstring-code-format = true # 格式化文档字符串中的代码示例
抑制格式化
fmt: off
matrix = [1,0,0, 0,1,0, 0,0,1]
fmt: on
result = some_call() # fmt: skip
与格式化器不兼容的规则
使用 ruff format 时禁用以下规则以避免冲突：
[tool.ruff.lint] ignore = [ "W191", # tab-indentation "E111", # indentation-with-invalid-multiple "COM812", # missing-trailing-comma "ISC002", # multi-line-implicit-string-concatenation "Q000", # bad-quotes-inline-string "Q001", # bad-quotes-multiline-string "Q002", # bad-quotes-docstring ]
CI 与 Pre-commit 集成
GitHub Actions
- name: Lint and format check run: | ruff check . ruff format --check .
pre-commit 钩子
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.9.0
hooks:
- id: ruff args: [--fix]
- id: ruff-format
迁移现有代码库
为所有当前违规自动添加 noqa 指令，然后逐步清理：
ruff check --add-noqa . # 为所有失败行添加 noqa ruff check --extend-select RUF100 --fix . # 随时间移除过期 noqa
快速参考
任务 | 命令 检查当前目录 | ruff check 检查并修复安全违规 | ruff check --fix 格式化当前目录 | ruff format 检查格式（CI 模式） | ruff format --check 仅排序导入 | ruff check --select I --fix 解释某条规则 | ruff rule F401 列出所有规则 | ruff linter 显示某文件的活动配置 | ruff check --show-settings <file.py> 标记未使用的 noqa 注释 | ruff check --extend-select RUF100
附加资源
参考文件
references/rule-categories.md — 详细的规则前缀、常见忽略及按类别指导
references/configuration-guide.md — 检查器与格式化器的完整配置选项
示例文件
examples/pyproject.toml — 生产可用的 pyproject.toml 配置
examples/ruff.toml — 独立的 ruff.toml 配置（monorepo 根目录）
examples/pre-commit-config.yaml — pre-commit 钩子配置