10倍提速！Ruff CLI命令完全指南：从check到format参数全解析
项目地址: https://gitcode.com/GitHub_Trending/ru/ruff 你是否还在忍受Flake8的龟速检查？是否为Black的冗长配置头疼？本文将带你掌握Ruff这款由Rust编写的超高速Python代码检查工具和格式化程序的所有CLI命令参数，让代码质量提升效率翻倍。读完本文，你将能够：
- 熟练使用
ruff check命令进行代码检查并修复问题 - 掌握
ruff format命令的高级格式化技巧 - 了解所有可用命令参数及其使用场景
- 通过配置文件与命令行参数的结合实现高效工作流
Ruff简介
Ruff是一款用Rust编写的极其快速的Python代码检查工具和代码格式化程序，比现有工具快10-100倍。它可以替代Flake8、isort、Black等多个工具，同时提供统一的用户体验和更高的性能。
核心优势
- 速度：比Flake8快10-100倍，比Black快10倍以上
- 功能全面：集成了800多个内置规则，支持代码检查和格式化
- 易于使用：简单直观的CLI接口，丰富的配置选项
- 可扩展性：支持插件系统，可自定义规则和格式化风格
安装Ruff
在开始使用Ruff之前，需要先安装它。Ruff提供多种安装方式，适用于不同的操作系统和环境：
# 使用pip安装
pip install ruff
# 使用uv安装（推荐）
uv tool install ruff@latest
# 使用curl安装（适用于macOS和Linux）
curl -LsSf https://astral.sh/ruff/install.sh | sh
# 使用Homebrew安装（macOS）
brew install ruff
安装完成后，可以通过以下命令验证安装是否成功：
ruff --version
ruff check：代码检查命令详解
ruff check是Ruff的核心命令，用于对Python代码进行静态分析，检查潜在问题并提供修复建议。
基本用法
# 检查当前目录下的所有Python文件
ruff check
# 检查指定目录
ruff check path/to/code/
# 检查单个文件
ruff check path/to/code/file.py
# 检查多个文件
ruff check file1.py file2.py file3.py
主要参数
| 参数 | 描述 | 示例 |
|---|---|---|
--fix | 自动修复可修复的问题 | ruff check --fix |
--select | 指定要启用的规则或规则组 | ruff check --select F,E4 |
--ignore | 指定要忽略的规则或规则组 | ruff check --ignore F401 |
--extend-select | 在默认规则基础上添加额外规则 | ruff check --extend-select B |
--extend-ignore | 在默认忽略规则基础上添加额外忽略规则 | ruff check --extend-ignore E501 |
--exclude | 指定要排除的文件或目录 | ruff check --exclude venv/ |
--include | 指定要包含的文件模式 | ruff check --include "*.py" |
--quiet | 仅输出错误信息，不显示进度 | ruff check --quiet |
--verbose | 显示详细输出信息 | ruff check --verbose |
--config | 指定配置文件路径 | ruff check --config path/to/ruff.toml |
--preview | 启用预览功能和规则 | ruff check --preview |
--unsafe-fixes | 允许执行不安全的修复操作 | ruff check --fix --unsafe-fixes |
--exit-zero | 即使发现问题也返回0退出码 | ruff check --exit-zero |
--exit-non-zero-on-fix | 如果进行了修复，返回非零退出码 | ruff check --fix --exit-non-zero-on-fix |
--cache-dir | 指定缓存目录路径 | ruff check --cache-dir .ruff_cache |
--no-cache | 禁用缓存 | ruff check --no-cache |
规则选择与配置
Ruff使用类似Flake8的规则代码系统，每个规则由一个1-3个字母的前缀和三位数字组成（如F401）。可以通过前缀选择一整组规则，如F表示所有Pyflakes规则。
# 仅启用F401规则
ruff check --select F401
# 启用所有F(Flake8)和E(pycodestyle)规则
ruff check --select F,E
# 启用所有规则
ruff check --select ALL
更多规则相关信息，请参考官方文档：rules.md
自动修复功能
Ruff提供强大的自动修复功能，可以修复许多常见的代码问题，如移除未使用的导入、调整缩进、纠正命名约定等。
# 自动修复可修复的问题
ruff check --fix
# 执行不安全的修复
ruff check --fix --unsafe-fixes
# 仅修复特定规则相关的问题
ruff check --fix --select F401,F841
修复功能的详细配置选项，可以参考配置文档。
ruff format：代码格式化命令详解
ruff format命令用于按照预定义的代码风格自动格式化Python代码，使代码风格保持一致，减少手动调整的工作量。
基本用法
# 格式化当前目录下的所有Python文件
ruff format
# 格式化指定目录
ruff format path/to/code/
# 格式化单个文件
ruff format path/to/code/file.py
# 检查格式问题但不修改文件
ruff format --check
主要参数
| 参数 | 描述 | 示例 |
|---|---|---|
--check | 检查格式问题但不修改文件 | ruff format --check |
--diff | 显示格式化前后的差异 | ruff format --diff |
--quiet | 仅输出错误信息 | ruff format --quiet |
--verbose | 显示详细输出信息 | ruff format --verbose |
--config | 指定配置文件路径 | ruff format --config path/to/ruff.toml |
--preview | 启用预览格式功能 | ruff format --preview |
--line-length | 指定行长度限制 | ruff format --line-length 100 |
--quote-style | 指定引号风格（single/double） | ruff format --quote-style single |
--indent-style | 指定缩进风格（space/tab） | ruff format --indent-style tab |
--indent-width | 指定缩进宽度 | ruff format --indent-width 4 |
高级格式化选项
Ruff的格式化功能提供了多种高级选项，可以通过命令行参数或配置文件进行设置：
# 使用单引号和4个空格缩进
ruff format --quote-style single --indent-width 4
# 设置行长度为100
ruff format --line-length 100
# 启用文档字符串格式化
ruff format --docstring-code-format
这些选项也可以在配置文件中设置，实现项目级别的统一格式化风格：
# pyproject.toml
[tool.ruff.format]
quote-style = "single"
indent-style = "space"
indent-width = 4
line-length = 100
docstring-code-format = true
更多格式化选项，请参考格式化文档。
其他实用命令
ruff help：获取帮助信息
# 获取命令列表
ruff help
# 获取特定命令的帮助
ruff help check
ruff help format
ruff version：查看版本信息
ruff --version
ruff rule：查看规则详情
# 查看特定规则的详细信息
ruff rule F401
ruff rule E501
配置文件与命令行参数结合使用
Ruff支持使用配置文件（如pyproject.toml、ruff.toml）进行持久化配置，同时也允许通过命令行参数覆盖配置文件中的设置。这种灵活性使得Ruff可以适应不同项目和团队的需求。
配置文件示例
# pyproject.toml
[tool.ruff]
line-length = 88
indent-width = 4
target-version = "py39"
[tool.ruff.lint]
select = ["E", "F", "B", "I"]
ignore = ["F401"]
fixable = ["ALL"]
unfixable = []
[tool.ruff.format]
quote-style = "double"
indent-style = "space"
line-ending = "auto"
命令行参数覆盖配置文件
# 使用配置文件中的设置
ruff check
# 临时覆盖行长度设置
ruff check --line-length 100
# 临时添加额外规则
ruff check --extend-select SIM
这种方式允许在不修改配置文件的情况下，针对特定场景临时调整Ruff的行为。
工作流示例
结合Ruff的各种命令和参数，可以构建高效的代码质量保障工作流。
开发过程中的快速检查与格式化
# 检查并自动修复问题
ruff check --fix
# 格式化代码
ruff format
提交代码前的全面检查
# 检查所有Python文件，启用严格模式
ruff check --select ALL --fix
# 确保代码格式符合要求
ruff format --check
集成到CI/CD流程
# .github/workflows/ruff.yml
name: Ruff
on: [push, pull_request]
jobs:
ruff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v4
- run: pip install ruff
- run: ruff check --select ALL --fix --exit-non-zero-on-fix
- run: ruff format --check
与编辑器集成
Ruff提供了多种编辑器集成方案，可以在开发过程中实时检查和格式化代码：
常见问题与解决方案
如何解决Ruff与其他工具的冲突？
当Ruff与其他代码检查或格式化工具一起使用时，可能会出现规则冲突。解决方法是：
- 逐步迁移到Ruff，逐步禁用其他工具
- 通过配置文件精细调整Ruff的规则
- 使用
--ignore参数排除与其他工具冲突的规则
如何处理误报？
如果Ruff报告了误报（false positive），可以：
-
使用
# noqa注释忽略特定行的规则：x = 1 # noqa: F841 -
在配置文件中全局忽略规则：
[tool.ruff.lint] ignore = ["F401"] -
提交issue报告误报：https://github.com/astral-sh/ruff/issues
如何自定义规则？
Ruff支持通过配置文件自定义规则的行为：
# 自定义规则 severity
[tool.ruff.lint.rules]
"F401" = { severity = "error" }
"B007" = { severity = "warning" }
# 自定义规则参数
[tool.ruff.lint.pylint]
max-args = 8
更多自定义选项，请参考配置文档。
总结
Ruff作为一款由Rust编写的超高速Python代码检查和格式化工具，通过统一的CLI接口和丰富的参数选项，为Python开发者提供了高效、一致的代码质量保障方案。本文详细介绍了Ruff的主要命令（check、format）及其参数，以及如何将Ruff集成到开发工作流中。
通过掌握Ruff的CLI命令和参数，你可以：
- 大幅提高代码检查和格式化的速度
- 统一团队代码风格
- 减少手动调整代码的工作量
- 及早发现和修复代码问题
Ruff的开发非常活跃，新功能和改进不断推出。建议定期更新Ruff以获取最新功能和性能优化：
pip install --upgrade ruff
要了解更多关于Ruff的信息，可以访问以下资源：
- 官方文档：docs.astral.sh/ruff
- GitHub仓库：github.com/astral-sh/ruff
- 规则参考：docs.astral.sh/ruff/rules
现在，开始使用Ruff提升你的Python开发效率吧！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
