代码检查是编写整洁、可读且可共享代码的关键环节。Ruff这类代码检查工具能分析代码，排查语法错误、风格问题和可疑的代码结构。在提交并共享代码前，通过代码检查可以提前解决问题，提升代码质量。

Ruff是一款现代化的代码检查工具，运行速度极快且界面简洁，上手难度低。它还支持无缝替代Flake8、isort、Black等多款主流的代码检查和格式化工具，如今已成为最受欢迎的Python代码检查工具之一。

通过本教程，你将学会：

• • 安装Ruff
• • 检查Python代码中的错误
• • 自动修复代码检查发现的错误
• • 使用Ruff格式化代码
• • 配置可选参数，让代码检查效果更优

要充分理解本教程内容，你需要熟悉Python虚拟环境、第三方模块安装，且能熟练使用终端。

安装Ruff

了解了代码检查的重要性，以及Ruff这款工具的强大之处后，接下来我们开始安装。好在Ruff支持开箱即用，无需复杂的安装步骤和初始配置就能直接使用。

假设你的项目已配置好虚拟环境，可通过以下几种方式安装Ruff：

终端命令

$ python -m pip install ruff

除了pip，macOS或Linux用户还可以通过Homebrew安装：
终端命令

$ brew install ruff

Conda用户可通过conda-forge源安装：
终端命令

$ conda install -c conda-forge ruff

Arch、Alpine、openSUSE Linux用户可直接通过系统官方软件源安装，具体步骤可参考Ruff官方文档的安装页面。

此外，如果你希望所有项目都能使用Ruff，也可以通过pipx进行安装。

安装完成后，可通过ruff version命令验证安装是否成功：
终端命令

$ ruff version
ruff 0.4.7

若终端中无法识别ruff命令，你可能需要关闭并重新打开终端，或启动新的终端会话，让命令加入系统环境变量。

Python代码检查

需要注意的是，代码检查能让代码保持一致性且避免语法错误，但并不能保证代码完全无逻辑漏洞。代码中的逻辑bug需要通过调试器和充分的测试来排查，这部分内容本教程不做讲解。接下来的章节，我们将学习如何使用Ruff检查代码错误并提升开发效率。

查找错误

以下是一个名为one_ring.py的简单脚本，运行后会从元组中随机抽取一个《指环王》角色名，并判断该角色是否曾佩戴至尊魔戒。这段代码无实际业务用途，仅作示例使用。无论代码库规模大小，使用Ruff检查错误的步骤都是一致的：

Python代码
one_ring.py

import os
import random

CHARACTERS = ("Frodo", "Sam", "Merry", "Pippin", "Aragorn", "Legolas", "Gimli", "Boromir", "Gandalf", "Saruman", "Sauron")

def random_character():
    return random.choice(CHARACTERS)

def ring_bearer():
    return name in ("Frodo", "Sam")

if __name__ == "__main__":
    character = random_character()
    if ring_bearer(character):
        print(f"{character} is a ring bearer")
    else:
        print(f"{character} is not a ring bearer")

如果你足够细心，可能已经发现了代码中的问题，即便没有发现也没关系，Ruff能帮我们排查出所有错误。

Ruff命令行的基础核心命令是check，默认情况下，该命令会检查当前目录下的所有文件。本示例中，直接运行无参的check命令即可，检查上述代码后会输出以下结果：

终端命令

$ ruff check
one_ring.py:1:8: F401 [*] 导入os模块但未使用
one_ring.py:10:12: F821 名称name未定义
发现2个错误。
[*] 1个错误可通过--fix参数自动修复。

检查成功！Ruff排查出了两个错误，不仅标注了错误所在的文件和行号，还给出了错误码和错误描述，同时提示其中1个错误支持自动修复。

注：本示例中目录下仅有one_ring.py一个文件，若存在多个文件，可通过ruff check one_ring.py检查单个文件；若你的代码文件存放在src/目录且包含多级子目录，可通过ruff check src/检查src/目录下的所有文件和子目录。

你可以通过--fix参数让Ruff自动修复可修复的错误，执行该命令后效果如下：
终端命令

$ ruff check --fix
one_ring.py:9:12: F821 名称name未定义
发现2个错误（1个已修复，1个未修复）。

未使用的导入语句已被修复，对应的代码行从one_ring.py中删除，剩余的一个错误无法自动修复。这处错误的问题所在对你而言可能显而易见，但也可能存在疑惑。

注：注意到剩余错误的行号发生变化了吗？这是因为未使用的导入语句被删除后，后续所有代码行都上移了一行。

好在Ruff提供了错误码，且支持在本地快速查询错误详情，无需翻阅在线文档。这就需要用到Ruff的第二个命令：rule。

通过ruff rule命令搭配错误码，就能查看该错误的详细说明，包括代码示例：
终端命令

$ ruff rule F821

运行该命令后，终端会以Markdown格式输出以下详细信息：

Markdown文本

# 未定义的名称（F821）
衍生自PyFlakes代码检查工具。

## 检查规则
检查代码中使用的未定义名称。

## 错误危害
使用未定义的名称会导致代码运行时抛出NameError异常。

## 错误示例
```python
def double():
    return n * 2  # 若调用double时n未定义，会抛出NameError异常

正确写法

def double(n):
    return n * 2

## 参考资料
- [Python官方文档：命名与绑定](https://docs.python.org/3/reference/executionmodel.html#naming-and-binding)

结合错误码的详细说明，能发现示例代码的问题所在：第9行的name变量未作为参数传入ring_bearer()函数。

要修复该错误，只需为ring_bearer()函数添加name参数即可：
Python代码 one_ring.py

# ...

def ring_bearer(name):
    return name in ("Frodo", "Sam")

修改完成后，再次运行ruff check验证是否修复成功：
终端命令

$ ruff check
所有检查通过！

完美！两个错误均已修复，修复后的完整代码如下：
Python代码
one_ring.py

 import random

CHARACTERS = ("Frodo", "Sam", "Merry", "Pippin", "Aragorn", "Legolas", "Gimli", "Boromir", "Gandalf", "Saruman", "Sauron")

def random_character():
    return random.choice(CHARACTERS)

def ring_bearer(name):
    return name in ("Frodo", "Sam")

if __name__ == "__main__":
    character = random_character()
    if ring_bearer(character):
        print(f"{character} 是魔戒持有者")
    else:
        print(f"{character} 不是魔戒持有者")

每次修改代码后都手动运行ruff check会比较繁琐，好在Ruff提供了对应的解决方案。下一节我们将学习如何让Ruff实时监控代码并检查错误。

提升工作流效率

在开发过程中，Ruff能实现实时代码检查，让你随时发现错误，从而提升整体开发效率。只需打开新的终端窗口，为check命令添加--watch参数，即可开启实时检查模式：

$ ruff check --watch

运行上述命令后，终端会输出以下内容：

[下午14:04:01] 启动代码检查器监听模式...
[下午14:04:01] 未发现错误，正在监听文件变化。

此时你的代码已经没有错误了？其实不然。下一节我们将学习Ruff默认配置下不会检查的问题类型。

发现更多错误

虽然Ruff排查出的错误已全部修复，但代码仍有优化空间，one_ring.py中还有几处可以改进的地方，能让代码更整洁、可读性更高，最明显的问题是第3行的CHARACTERS元组代码行过长。

你可能会疑惑，为什么Ruff默认没有检查出这个问题？答案可以在官方文档中找到：

Ruff默认启用Flake8的F类规则，以及部分E类规则，会忽略所有与格式化工具（如ruff format、Black）重叠的风格类规则。

默认配置下，Ruff不会检查代码行长度问题，但你可以手动指定需要启用或禁用的额外规则，通过--select参数可启用所有E类规则，或单独启用某一条具体规则：

$ ruff check --select E
one_ring.py:4:89: E501 代码行过长（122个字符 > 88个字符）
发现1个错误。

$ ruff check --select E501
one_ring.py:4:89: E501 代码行过长（122个字符 > 88个字符）
发现1个错误。

现在我们找到了这处隐藏的问题，但注意到终端并未提示该错误可通过--fix参数自动修复。不用担心，Ruff提供了专门的命令来修复这类格式化错误，下一节我们将学习ruff format命令的使用。

Python代码格式化

Ruff默认的格式化规则设计合理，且被打造为Black工具的即插即用替代方案，format格式化命令从Ruff 0.1.2版本开始支持。

和check命令一样，format命令也支持传入单个文件或目录路径作为可选参数。本教程的示例中仅有一个文件，直接运行无参的format命令即可：

$ ruff format
1个文件已完成格式化

格式化后的one_ring.py代码可读性更高，且格式规范统一：

 import random

CHARACTERS = (
    "Frodo",
    "Sam",
    "Merry",
    "Pippin",
    "Aragorn",
    "Legolas",
    "Gimli",
    "Boromir",
    "Gandalf",
    "Saruman",
    "Sauron",
)


def random_character():
    return random.choice(CHARACTERS)


def ring_bearer(name):
    return name in ("Frodo", "Sam")


if __name__ == "__main__":
    character = random_character()
    if ring_bearer(character):
        print(f"{character} 是魔戒持有者")
    else:
        print(f"{character} 不是魔戒持有者")

可以看到，之前第3行的代码行过长问题已被解决。虽然元组的定义占用了更多行数，但角色名的可读性大幅提升，同时也让代码评审更高效——大多数工具和平台在展示代码差异时，只会显示实际修改的内容，而非整个数据结构。

除此之外，Ruff还让函数之间的空行保持统一，符合PEP 8编码规范中“函数之间保留两个空行”的要求。

最后一个细节优化是，Ruff为文件末尾补充了缺失的换行符，这一点看似微不足道，但却是规范的编码习惯。

本示例的代码量较少，格式化过程简单直接。对于规模更大的代码库，格式化可能会产生大量修改，甚至存在极少数破坏代码功能的风险，不过格式化工具通常会以“安全”为首要原则，此类情况极少发生。如需了解Ruff中关于非安全修复的更多内容，可参考官方文档的修复安全性章节。

如果你想在格式化前预览代码修改内容，可为format命令添加--diff参数，查看拟执行的修改：
文件修改对比（diff）

--- one_ring.py
+++ one_ring.py
@@ -1,16 +1,31 @@
 import random


-CHARACTERS = ("Frodo", "Sam", "Merry", "Pippin", "Aragorn", "Legolas", "Gimli", "Boromir", "Gandalf", "Saruman", "Sauron")
+CHARACTERS = (
+    "Frodo",
+    "Sam",
+    "Merry",
+    "Pippin",
+    "Aragorn",
+    "Legolas",
+    "Gimli",
+    "Boromir",
+    "Gandalf",
+    "Saruman",
+    "Sauron",
+)
+

 def random_character():
     return random.choice(CHARACTERS)

+
 def ring_bearer(name):
     return name in ("Frodo", "Sam")

+
 if __name__ == "__main__":
     character = random_character()
     if ring_bearer(character):
         print(f"{character} 是魔戒持有者")
     else:
-        print(f"{character} 不是魔戒持有者")
\ 文件末尾无换行符
+        print(f"{character} 不是魔戒持有者")

1个文件将被格式化

上述基础用法可能已能满足你的日常代码格式化需求，但有时你可能需要自定义代码行长度、启用或禁用特定规则。如果每次检查代码都在终端中手动输入所有规则，会非常繁琐，好在Ruff提供了更优的解决方案。

Ruff支持高度自定义配置，虽非必选，但能大幅提升使用体验。下一节我们将介绍基础的配置方法。

配置Ruff

如果你需要检查规模较大的代码库、团队多人协作开发，或希望自定义Ruff的使用体验，可以将配置项写入TOML格式的配置文件中，支持的文件包括ruff.toml、.ruff.toml，也可以直接写入项目已有的pyproject.toml文件。

如前所述，Ruff的默认配置设计合理，所有默认配置项均可在Ruff官方文档的配置页面中查看，官方也详细列出了所有可自定义的配置项。以下是一个可直接添加到项目中的简易ruff.toml配置示例：

TOML代码
ruff.toml

line-length = 88

[lint]
select = ["E501", "I"]

[format]
docstring-code-format = true
docstring-code-line-length = 72

以下是相同配置在pyproject.toml文件中的写法，唯一的区别是所有配置表的表头都需要添加tool.ruff前缀：

TOML代码
pyproject.toml

[tool.ruff]
line-length = 88

[tool.ruff.lint]
select = ["E501", "I"]

[tool.ruff.format]
docstring-code-format = true
docstring-code-line-length = 72

上述配置示例中包含了几个新的规则：和之前的操作一致，我们启用了E501规则，该规则会在代码行长度超过默认的88个字符时抛出错误。

除了E501规则，我们还启用了所有I类规则。I类规则是isort工具的专属规则，isort是一款常用的Python导入语句检查和格式化工具。启用该配置后，你无需再单独使用isort和Black工具，减少了需要维护的工具数量和开发依赖。

在配置的6-8行，我们设置了Ruff会对文档字符串进行格式化，且文档字符串的代码行长度限制为72个字符。该数值可自定义，很多开发者会将其设置为88个字符，与代码行长度保持一致。需要注意的是，Ruff默认不会格式化文档字符串。

Ruff提供了大量的代码检查和格式化配置项，建议你翻阅官方的配置列表，选择适合自己项目的配置项。

如果你有使用其他代码检查工具的经验，欢迎在评论区分享你最喜欢的规则和自定义配置。

后续步骤

通过本教程，你了解了代码检查的重要性，以及如何使用Ruff打造整洁、可读、无错误的代码，接下来不妨在实际项目中尝试使用这款工具。

如前所述，Ruff拥有丰富的配置项，能让代码检查的效果更贴合你的需求。同时它还支持多种集成方式，进一步提升开发效率，包括VS Code扩展、PyCharm插件、Git提交前钩子和GitHub Actions自动化工作流。

总结

Ruff是一款运行速度极快的Python代码检查和格式化工具，能有效提升代码质量和可维护性。本教程介绍了Ruff的入门方法，展示了其核心功能，并验证了它的实用价值。

通过本教程，你学会了：

• • 安装Ruff
• • 检查Python代码中的错误
• • 自动修复代码检查发现的错误
• • 使用Ruff格式化代码
• • 配置可选参数，让代码检查效果更优

掌握这款工具后，你的代码质量将更上一个台阶，既能保证代码的专业性，更重要的是能大幅减少代码中的错误。

参考文献

• • https://realpython.com/ruff-python/