【AI总结】一篇吃透 Ruff CLI：从入门到进阶的完整命令手册

一篇吃透 Ruff CLI：从入门到进阶的完整命令手册

ruff github：https://github.com/astral-sh/ruff
ruff docs：https://docs.astral.sh/ruff/

---

一、为什么选 Ruff？

特性	传统方案	Ruff
速度	Flake8+isort+Black 组合 ≈ 5–10 s	Rust 实现 < 0.3 s
规则覆盖	需多工具拼积木	700+ 规则内置
配置	多个文件	单文件 pyproject.toml
自动修复	少量	400+ 规则可 --fix

---

二、安装 & 升级

# 全局安装（推荐）
uv tool install ruff          # 使用 uv
pipx install ruff             # 或 pipx
pip install ruff              # 传统 pip

# 升级
uv tool upgrade ruff

---

三、核心子命令思维导图

ruff
├─ check      # 静态检查（lint）
├─ format     # 代码格式化
├─ fix        # 仅修复
├─ rule       # 查看规则
├─ list       # 列出规则
├─ clean      # 清缓存
└─ version    # 版本

---

四、ruff check —— 一把梭搞定 Lint

1. 最常用组合

ruff check .                    # 递归检查
ruff check --fix                # 自动修复
ruff check --fix --unsafe       # 含不安全修复

2. 精准控制

ruff check --select E9,F63      # 只看错误 & 未定义
ruff check --ignore E501,W503   # 忽略行过长 & 运算符换行
ruff check --extend-select I    # 追加 isort 规则

3. 持续集成

# 输出 GitHub 兼容格式
ruff check --output-format=github

GitHub Actions 模板：

- uses: astral-sh/ruff-action@v2
  with:
    src: ./src
    args: --output-format=github

---

五、ruff format —— Black 的极速替代

ruff format .                   # 就地格式化
ruff format --check             # 仅检查，不改文件
ruff format --diff              # 打印 diff，适合 CI

与 Black 差异速览

规则	Black	Ruff
行长	88 默认	同 Black，可改
字符串引号	优先双引号	同 Black
速度	1x	30x+

---

六、规则字典：ruff rule & ruff list

# 查看单条规则
ruff rule E501
# 输出 JSON 列表
ruff list --format=json | jq '.[] | select(.code=="F401")'

---

七、配置文件示例

pyproject.toml（推荐）

[tool.ruff]
line-length = 100
target-version = "py311"
select = ["E", "F", "W", "I", "UP"]
ignore = ["E501", "COM812"]
fixable = ["ALL"]
unfixable = ["F601"]

[tool.ruff.per-file-ignores]
"tests/*" = ["S101"]  # 允许 assert

ruff.toml（极简）

line-length = 88
select = ["E", "F"]

---

八、与 uv 的丝滑配合

# 免安装即用
uvx ruff check .

# 全局装一份
uv tool install ruff
ruff --version

---

九、实战工作流（本地 → CI）

阶段	命令
本地开发	ruff check --fix . && ruff format .
预提交钩子	pre-commit install（官方 hook 已内置）
CI 检查	ruff check --output-format=github
发布前	ruff check && ruff format --check

---

十、常见问题 FAQ

Q1：如何关闭某行？

import os  # noqa: F401

Q2：如何忽略整个目录？
在配置里加：

[tool.ruff]
exclude = ["migrations", "build"]

Q3：与 isort/black 共存？
无需共存，Ruff 已集成。

---

十一、一键脚本（保存为 lint.sh）

#!/usr/bin/env bash
set -e
ruff check --fix .
ruff format .
echo "✅ Lint & format done"

赋予可执行权限：

chmod +x lint.sh