使用 Ruff 进行 Python 代码格式化与静态检查

boyanx2周前 (06-30)技术教程5

随着 Python 项目的规模增大，保持一致的代码风格和高质量的代码变得尤为重要。Ruff 是一个现代、高性能、支持 lint 和格式化的 Python 工具，能帮助你快速发现并修复常见代码问题。

本文将介绍：

Ruff 的作用与工作原理
如何安装与配置 Ruff
VSCode 等开发环境中的集成方式
常用参数说明
配置案例

1. 什么是 Ruff？

Ruff 是由 Astral 团队开发的一个 Python 静态检查器和格式化器，主打：

速度极快（使用 Rust 编写）
功能全面：集成 Flake8、isort、pycodestyle、autoflake、pylint 等常见工具的规则
自动修复：支持大部分问题自动修复
代码格式化：可以替代 Black 进行统一格式化

2. 安装 Ruff

使用 pip 安装 Ruff（建议加到开发依赖）：

pip install ruff

3. Ruff 的工作原理

Ruff 的工作主要分为两个阶段：

阶段	命令	功能
Lint 检查（静态分析）	ruff check	分析代码错误、风格问题（未使用变量、导入顺序等）
自动格式化	ruff format	格式化代码（缩进、引号风格、括号等）

其中：

ruff check . --fix 可以自动修复大部分 lint 问题，包括删除未使用 import、合并重复导入等。
ruff format . 主要用于统一格式，不会做“语义删除”（比如不会删未使用 import）。

4. 项目结构建议

css


复制编辑
your_project/
├── pyproject.toml        ← Ruff 配置写在这里
├── .vscode/
│   └── settings.json     ← VSCode 编辑器配置
├── src/
│   └── main.py
└── tests/
    └── test_main.py

5. 配置 Ruff（pyproject.toml）

在项目根目录创建或编辑 pyproject.toml，加入以下内容：

[tool.ruff]
line-length = 88                  # 最大行长度
target-version = "py38"          # Python 目标版本
src = ["src", "tests"]           # 源码路径

[tool.ruff.lint]
select = ["E", "F", "I", "W"]     # 开启的规则类型
ignore = ["E501"]                # 忽略某些规则（如行太长）
fixable = ["ALL"]                # 允许自动修复的规则

[tool.ruff.format]
quote-style = "double"           # 使用双引号
indent-style = "space"           # 使用空格缩进

select常见规则分类：

规则代码	说明
E	pycodestyle（代码风格）
F	pyflakes（错误检测）
I	import 排序（类似 isort）
W	警告信息（如未使用变量）

6. 集成 VSCode

在 .vscode/settings.json 中配置如下，实现“自动保存时格式化 + 实时 lint”：

{
  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 1000,
  "editor.formatOnSave": true,

  // 使用 Ruff 格式化器
  "python.formatting.provider": "ruff",

  // 启用 Ruff lint
  "python.linting.enabled": true,
  "python.linting.ruffEnabled": true,
  "python.linting.ruffArgs": ["--fix"],

  // 保存时执行所有修复操作
  "editor.codeActionsOnSave": {
    "source.fixAll": true
  }
}

7. 常用命令总结

命令	功能
ruff check .	检查代码（不修复）
ruff check . --fix	检查并修复问题（推荐日常使用）
ruff format .	格式化代码（等价于 Black）