如何在Python项目中使用Ruff提升代码质量检查速度

Ruff比flake8+isort+pydocstyle快得多，因其用Rust编写、不启动Python解释器、单进程内完成解析与检查，跳过import解析和动态插件加载等开销，典型项目下快10–100倍，从秒级降至毫秒级。

为什么 Ruff 比 flake8 + isort + pydocstyle 组合快得多

Ruff 用 Rust 编写，不启动 Python 解释器，解析和检查都在单进程内完成。它跳过了 AST 构建前的 import 解析、动态插件加载等开销，典型项目下比传统工具链快 10–100 倍。这不是“稍快一点”，而是从秒级降到毫秒级——ruff check 在中等规模项目（5k 行）里通常

常见误判是“Ruff 功能少所以快”，其实它已覆盖 pyflakes、pycodestyle、isort、pydocstyle、eradicate 等 20+ 工具的规则，且支持自定义规则（通过 rule 配置项启用/禁用）。

如何在 pre-commit 中正确集成 Ruff

直接替换 flake8 或 isort 的 hook 很容易出错：Ruff 默认不格式化代码，也不自动修复所有问题；它分 check（只报错）和 format（仅限部分规则，如缩进、空行）两个子命令。

• pre-commit 配置必须显式指定 types: [python]，否则可能跳过 .pyi 或 __init__.py
• 若想自动修复（如 E501 行长、I001 导入排序），需加 --fix 参数，但注意：--fix 不会修改未提交文件，只作用于 git 暂存区（staged）文件
• 推荐配置两阶段 hook：先 ruff check --fix 自动修正常见风格问题，再 ruff check --exit-non-zero-on-fix 确保无残留可修复项

repos:  - repo: https://github.com/astral-sh/ruff-pre-commit    rev: v0.6.9    hooks:      - id: ruff-pre-commit        args: [--fix]      - id: ruff-pre-commit        args: [--exit-non-zero-on-fix]        stages: [commit]

怎样让 Ruff 和 Black 共存不冲突

Ruff 的 format 子命令目前（v0.6.x）仅处理极小范围（如空行、引号风格），不能替代 Black。强行开启 ruff format 并与 Black 同时运行，会导致格式打架——比如 Black 强制双引号，而 Ruff 默认按源码引号风格保留。

立即学习“Python免费学习笔记（深入）”；

• 最佳实践：禁用 ruff format，只用 ruff check 做 lint，交由 Black 负责全部格式化
• 在 ruff.toml 中关闭格式相关规则：设置 format = false，并移除 RUF100（未使用导入）、ISC001（import 排序）等会被 Black 覆盖的检查项
• 若用 pre-commit，确保 black hook 在 ruff-pre-commit 之后执行，避免 Ruff 报告 Black 生成的临时样式问题

哪些 Ruff 配置项最容易被忽略却影响大

默认配置偏保守，很多团队上线后才发现规则太松或太严。几个关键点：

• select 列表没显式声明时，Ruff 只启用安全子集（如 E、F 类错误），漏掉大量风格建议（I、Q、UP）——建议至少加 I（isort）、Q（f-string 引号）、UP（升级提示）
• line-length = 88 必须和 black 一致，否则 E501 会误报；Ruff 不读取 pyproject.toml 中 [tool.black] 的配置
• extend-exclude 要包含 migrations/、venv/、.eggs/，否则首次运行可能扫描整个虚拟环境，卡住数秒
• 对 typing-heavy 项目，开启 py-version = "3.11"（或对应版本），否则 UP007（Union 提示符）等新语法规则不会触发

真正难的是平衡：开太多规则会让 CI 突然失败，开太少又失去意义。建议从 ruff check --select=E,F,I 小步开始，每周加一组规则，配合 --output-format=github 直接定位 PR 中的问题行。