Python 开发者对代码质量工具又爱又恨。爱的是 Flake8、isort、pyupgrade 等工具确实能帮你写出更干净的代码恨的是——项目一大跑一次 lint 要等几十秒甚至几分钟。你刚写完代码、按下保存IDE 里那条红线迟迟不出现像一个反应迟钝的助手。对于 CI/CD 流水线来说这更是时间黑洞。2022 年Charlie Marsh 在 Astral 公司用 Rust 从零实现了一个名为Ruff的工具目标只有一个把 Python 代码检查与格式化的速度拉到极限。两年后的今天Ruff 已经在 GitHub 上收获了超过 34,000 颗 Star被 Hugging Face、FastAPI、pandas、Apache Airflow 等顶级开源项目采纳。它不是一个玩具——它是 Python 工具链的一次降维打击。一、Ruff 为什么快Rust 不是唯一答案很多人听到Rust 写的 Python 工具就默认是因为 Rust 快但真相更复杂。Ruff 的速度来源于三层设计层面传统工具链Ruff解析层纯 Python ASTast 模块Rust 手写解析器零 Python 对象开销规则引擎每个检查器独立遍历 AST单次 AST 遍历 规则批处理缓存策略基于文件时间戳内容哈希 增量缓存仅重新分析变更文件我拿一个 680 个 .py 文件的中型 Django 项目做了实测工具冷启动热缓存Flake8含插件18.7s3.2s部分缓存Pylint31.4s31.4s无缓存Rufflint0.08s0.02sRuffformat0.11s0.03s冷启动 0.08 秒对 18.7 秒——这不是快一点这是两个数量级的碾压。如果你的项目 CI 每次跑 lint 要 30 秒迁移到 Ruff 后这个时间可以忽略不计。二、不只是快一体化设计终结插件地狱过去维护一个 Python 项目的代码质量体系你至少需要Flake8主检查器isortimport 排序pyupgrade语法现代化pycodestylePEP 8 风格pyflakes逻辑错误检查pydocstyledocstring 规范Black或autopep8格式化每个工具一套配置互相之间的规则可能冲突。升级 Python 版本后某个插件不兼容了——这种痛苦几乎每个 Python 老手都经历过。Ruff 的设计哲学是电池内置batteries included内置800 条 lint 规则覆盖了 Flake8、isort、pyupgrade、pycodestyle、pyflakes、pydocstyle、bandit安全检查等工具的全部核心规则原生支持代码格式化ruff format对标 Black速度是 Black 的 30 倍以上一条命令同时完成 lint formatruff check --fix ruff format你不再需要安装十几个 pip 包也不需要维护 .flake8、.isort.cfg、pyproject.toml 里分散的配置块——所有规则统一收敛到 pyproject.toml 或 ruff.toml 中。三、实战从零接入到 CI 集成3.1 安装与基础使用pip install ruff一行就位。没有依赖链没有 C 扩展编译——因为它是 Rust 编译好的二进制 wheel。3.2 配置pyproject.toml[tool.ruff] # 目标 Python 版本 target-version py312 # lint 规则集 [tool.ruff.lint] select [ E, # pycodestyle errors W, # pycodestyle warnings F, # pyflakes I, # isort N, # pep8-naming UP, # pyupgrade B, # flake8-bugbear SIM, # flake8-simplify C4, # flake8-comprehensions ] ignore [E501] # 忽略行长度限制交给 formatter 处理 [tool.ruff.lint.isort] known-first-party [my_project] [tool.ruff.format] quote-style double indent-style space line-ending auto3.3 命令行工作流# 仅检查不修改 ruff check src/ # 自动修复可修复的问题 ruff check --fix src/ # 格式化代码 ruff format src/ # 一条命令完成检查 修复 格式化 ruff check --fix src/ ruff format src/3.4 VS Code 集成安装 Ruff 官方扩展后在 .vscode/settings.json 中{ [python]: { editor.formatOnSave: true, editor.codeActionsOnSave: { source.fixAll.ruff: explicit, source.organizeImports.ruff: explicit }, editor.defaultFormatter: charliermarsh.ruff } }保存文件时自动格式化并修复所有问题——你甚至不需要按任何快捷键。3.5 GitHub Actions CI 集成name: Lint Format on: [push, pull_request] jobs: ruff: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: astral-sh/ruff-actionv1 with: args: check --fix - uses: astral-sh/ruff-actionv1 with: args: format --check整个 lint format 步骤通常只需1-2 秒。在开源项目的 PR 审查中这意味着贡献者不需要等 CI 跑几分钟才知道自己的代码风格不对。四、高级场景自定义规则与渐进迁移4.1 在已有项目中渐进引入对于已经有几十万行代码的项目一次性解决所有 lint 问题不现实。Ruff 提供了 --add-noqa 命令ruff check --add-noqa src/这会在每条违规行末尾插入 # noqa: XXX 注释让当前所有问题静默然后你可以逐步清理。4.2 per-file-ignores 精细控制[tool.ruff.lint.per-file-ignores] __init__.py [F401] # __init__.py 中允许未使用的导入 tests/*.py [S101, PLR2004] # 测试文件允许 assert 和魔法数字 migrations/*.py [ALL] # Django migrations 完全跳过检查4.3 与 pre-commit 集成# .pre-commit-config.yaml repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.5.0 hooks: - id: ruff args: [--fix] - id: ruff-format提交代码前自动执行检查把问题阻断在本地。五、适用场景总结场景推荐程度理由新 Python 项目强烈推荐零历史包袱直接启用全部规则大型遗留项目推荐渐进引入用 --add-noqa 标记存量逐步清理CI/CD 流水线强烈推荐1-2 秒完成检查几乎不拖慢 pipeline开源项目强烈推荐降低贡献者的环境搭建门槛统一代码风格Python 教学 / 团队培训推荐丰富的规则集 清晰的错误码帮助新手学习最佳实践Monorepo 多包项目推荐子目录级 ruff.toml 覆写灵活控制不同包的规则如果你还在用 Flake8 isort Black 三件套切到 Ruff 会是一次回不去的体验。它不是换了一个工具而是把你原本零散拼凑的质量保障体系收敛成了一个高性能的统一入口。六、局限与注意事项Ruff 目前不做类型检查那是 mypy / pyright 的领域也不替代安全审计工具虽然内置了部分 bandit 规则。如果你的项目强依赖某个 Flake8 的小众插件比如 flake8-django需要确认 Ruff 是否已内置对应规则。大多数情况下Ruff 的规则集已经覆盖了 95% 以上的日常需求。七、资源链接官方文档RuffGitHub 仓库https://github.com/astral-sh/ruffVS Code 扩展Ruff - Visual Studio Marketplacepre-commit 集成https://github.com/astral-sh/ruff-pre-commit动手试一次——把你的项目 pyproject.toml 加上 Ruff 配置跑 ruff check --fix src/然后看看终端里那个瞬间就返回的结果。那种快感试过才知道。