[!info] related notes

• 所属 MOC: python-moc, development-environment-moc
• 并列概念: pylance
• 相关工具: uv（同一团队开发）

Ruff

一句话定义

Ruff 是 Astral 公司（开发了 uv 的团队）用 Rust 编写的极速 Python 代码检查（Linting）和格式化（Formatting）工具，旨在替代 Flake8、Black、isort 等传统工具。

核心内容

解决什么问题

传统 Python 代码质量工具的问题：

• 速度慢：Flake8、Black 等工具运行缓慢
• 工具分散：需要同时使用多个工具（Flake8 + Black + isort）
• 配置复杂：每个工具都有自己的配置文件

核心优势

极速性能：

• Rust 编写，比传统工具快 10-100 倍
• 可以在保存时实时检查和格式化

统一工具：

• 替代 Flake8（代码检查）
• 替代 Black（代码格式化）
• 替代 isort（import 排序）
• 支持 700+ 条规则

与 Pylance 完美配合：

• Ruff 负责格式化和检查
• Pylance 负责类型检查和智能提示
• 两者分工明确，不冲突

最小例子

安装 Ruff

# 使用 uv 安装
uv add --dev ruff

# 或使用 pip
pip install ruff

基本使用

# 检查代码
ruff check .

# 自动修复可修复的问题
ruff check --fix .

# 格式化代码
ruff format .

VS Code 配置

在 .vscode/settings.json 中配置：

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports.ruff": "explicit"
    }
  }
}

边界与易混淆点

与 Pylance 的分工

功能	Ruff	Pylance
代码格式化	✅ 主要负责	❌ 不负责
Linting 检查	✅ 主要负责	⚠️ 部分支持
类型检查	❌ 不负责	✅ 主要负责
代码补全	❌ 不负责	✅ 主要负责
Import 排序	✅ 主要负责	⚠️ 可能冲突

常见误解

• 误解：Ruff 和 Pylance 会冲突
• 事实：只要配置正确（如上），它们是黄金搭档
• 误解：Ruff 只能检查代码
• 事实：Ruff 既能检查（Linting）也能格式化（Formatting）

适用场景

• ✅ 所有 Python 项目（强烈推荐）
• ✅ 需要极速代码检查和格式化
• ✅ 需要替代多个传统工具（Flake8、Black、isort）
• ✅ 与 uv 配合使用，打造现代化 Python 工具链

相关链接

• Ruff 官方文档
• Ruff GitHub
• uv（同一团队开发的 Python 工具链）