随着 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 的工作主要分为两个阶段：

其中：

• 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常见规则分类：

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. 常用命令总结