Ruff Visual Studio Code 扩展

这是一款适用于 Ruff 的 Visual Studio Code 扩展。Ruff 是一款速度极快的 Python 代码检查工具和代码格式化工具，采用 Rust 编写。该扩展可在 Visual Studio Marketplace 获取。

Ruff 可用于替代 Flake8（以及数十种插件）、Black、isort、pyupgrade 等工具，且其执行速度比任何单个工具快数十倍乃至数百倍。

本扩展内置 ruff==0.16.1。

主要功能

“快速修复”操作，用于可自动修复的违规问题（如未使用的导入）

“全部修复”：自动修复所有可自动修复的违规问题

“格式化文档”：与 Black 兼容的代码格式化

“整理导入”：与 isort 兼容的导入排序

要求

此扩展功能运行无需其他额外扩展，但我们建议安装以下任一扩展：

• VS Code Python 环境扩展。请注意，这需要 VS Code 1.100 或更高版本。
• 支持 Python 3.8+ 的 VSCode Python 扩展版本。

当安装了上述任一扩展时，Ruff 扩展会使用它在活动环境中定位 Ruff 二进制文件。如果在活动环境中未找到二进制文件，或者两个扩展均不可用，Ruff 将回退到 PATH 中找到的 Ruff 二进制文件或扩展捆绑的 Ruff 二进制文件。

请注意，已弃用的 ruff-lsp 服务器需要这些扩展之一来定位 Python 解释器。如果均未安装，Ruff 将改用其原生服务器。安装任一扩展后，请重新加载 VS Code 以启用 Python 环境检测。

用法

在 Visual Studio Code 中安装后，当你打开或编辑 Python 文件、Jupyter Notebook 文件或 Ruff 配置文件（pyproject.toml、ruff.toml 或 .ruff.toml）时，ruff 将自动执行。

如果你想禁用 Ruff，可以在 Visual Studio Code 中按工作区禁用此扩展。

修复安全性

Ruff 的自动修复分为“安全”和“不安全”两类。默认情况下，“全部修复”操作不会应用不安全的修复。但是，可以通过“快速修复”操作手动应用不安全的修复。若要在使用“全部修复”时应用不安全的修复，可以在 Ruff 配置文件中设置 unsafe-fixes = true，或在“Lint 参数”设置中添加 --unsafe-fixes 标志。

有关修复安全性工作原理的更多详细信息，请参阅 Ruff 修复文档。

Jupyter Notebook 支持

该扩展通过语言服务器协议（Language Server Protocol）3.17 版本中新增的 Notebook Document Synchronization 功能支持 Jupyter Notebooks。ruff-lsp 自 v0.0.43 版本起已实现此功能，可全面支持 Jupyter Notebooks 中 Python 文件现有的所有功能，包括诊断、代码操作和格式化。

这需要 Ruff 版本 v0.1.3 或更高版本。

原生服务器

Jupyter Notebook 支持已在 Ruff 0.6.0 中稳定，并默认进行 linting 和格式化。在此版本之前，原生服务器要求用户明确将 Jupyter Notebooks 包含在要进行 linting 和格式化的文件集中。这可以通过更新 Ruff 配置文件中的 extend-include 设置来实现。

[tool.ruff]
extend-include = ["*.ipynb"]

如需了解更多信息，请参阅 Ruff 文档的 Jupyter Notebook 发现 部分。

不受信任的工作区

于 v2024.32.0 版本新增

本扩展支持在 不受信任的工作区 中加载。当工作区不受信任时，即使 nativeServer 设置设为 off，扩展也将始终使用基于 Rust 的语言服务器。这是因为基于 Python 的语言服务器需要 Python 解释器才能运行，而这在不受信任的工作区中是不允许的。这也意味着扩展将始终使用捆绑的 ruff 二进制可执行文件，无论其他任何设置如何。

以下设置在不受信任的工作区中不受支持：

• ruff.configuration
• ruff.importStrategy
• ruff.interpreter
• ruff.path

设置

有关扩展中可用的完整设置列表，请参阅 Ruff 语言服务器文档。

配置 VS Code

你可以通过在 settings.json 中启用 editor.formatOnSave 操作，并将 Ruff 设置为默认格式化程序，来配置 Ruff 在保存时格式化 Python 代码：

{
  "[python]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "charliermarsh.ruff"
  }
}

并且，对于 Jupyter Notebooks：

{
  "notebook.formatOnSave.enabled": true,
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff"
  }
}

以及针对 Markdown 代码块。 请注意，目前这需要启用 预览模式， 此模式会改变格式化结果：

{
  "ruff.format.preview": true,
  "[markdown]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "charliermarsh.ruff"
  }
}

你可以通过在 settings.json 中启用 source.fixAll 操作，将 Ruff 配置为在保存时自动修复 lint 违规问题：

{
  "[python]": {
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit"
    }
  }
}

并且，对于 Jupyter Notebooks：

{
  "notebook.codeActionsOnSave": {
    "notebook.source.fixAll": "explicit"
  }
}

同样，你可以通过在 settings.json 中启用 source.organizeImports 操作，将 Ruff 配置为在保存时整理导入语句：

{
  "[python]": {
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit"
    }
  }
}

并且，对于 Jupyter Notebooks：

{
  "notebook.codeActionsOnSave": {
    "notebook.source.organizeImports": "explicit"
  }
}

综上所述，你可以通过以下 settings.json 配置 Ruff，使其在保存时进行格式化、修复和导入整理：

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

并且，对于 Jupyter Notebooks：

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

注：如果你在 VS Code 中使用 Ruff 来整理导入语句，同时也希望从命令行运行 Ruff，那么你需要通过在 extend-select 中添加 "I" 来启用 Ruff 的 isort 规则。

注：上述提及的笔记本配置会对每个单元格单独执行操作。这是 VS Code 处理笔记本操作的方式，与 ruff-lsp 无关。如果你希望一次性对整个笔记本执行操作，建议使用以 Ruff 为前缀的命令，例如 Ruff: Organize Imports 和 Ruff: Fix all auto-fixable problems。

如果你正在使用 VS Code Python 扩展，可以通过以下 settings.json 配置 VS Code，使其在保存时使用 Ruff 修复违规问题，然后使用 Black 扩展 进行重新格式化：

{
  "[python]": {
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit"
    },
    "editor.defaultFormatter": "ms-python.black-formatter"
  }
}

如果您希望将 Ruff 用作 linter，但继续使用 isort 扩展 对导入进行排序，可以通过以下 settings.json 禁用 Ruff 的导入排序功能：

{
  "[python]": {
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    }
  },
  "ruff.organizeImports": false
}

如果您希望在保存时运行 Ruff，但又不想让其他扩展在保存时运行，可以通过以下 settings.json 使用 Ruff 的作用域 source.fixAll 和 source.organizeImports 操作：

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

如果你希望运行 Ruff，但禁用代码格式化功能（无论是 Ruff 还是其他格式化工具提供的），请确保在 settings.json 中取消设置 editor.defaultFormatter：

{
  "[python]": {
    "editor.defaultFormatter": null,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit"
    }
  }
}

配置 Ruff

Ruff VS Code 扩展会遵循项目中 pyproject.toml、ruff.toml 或 .ruff.toml 文件中定义的任何 Ruff 配置（参见 Ruff 文档中的 配置 Ruff）。通常，我们建议通过 pyproject.toml 或 ruff.toml 配置 Ruff，这样你的配置可以在 VS Code 扩展与命令行工具之间共享，也能在项目的所有贡献者之间共享。

除非你使用的是 基于 Python 的语言服务器，否则你可以直接在 VS Code 中配置一些常用设置，例如 ruff.lineLength（用于配置 linter 和格式化器的行长度）或 ruff.lint.select（用于配置启用的 lint 规则）：

{
  "ruff.lineLength": 88,
  "ruff.lint.select": ["C", "E", "F", "W"]
}

若要使用自定义配置文件，请将 ruff.configuration 设置为您的 ruff.toml 或 pyproject.toml 文件路径：

{
  "ruff.configuration": "/path/to/ruff.toml"
}

最后，若要在所有项目中使用通用的 Ruff 配置，可考虑创建用户特定的 pyproject.toml 或 ruff.toml 文件，具体方法如 FAQ 中所述。

基于 Python 的语言服务器（ruff-lsp）

当满足以下条件时，Ruff 扩展将自动使用基于 Rust 的语言服务器（ruff server）：

1. ruff 可执行文件的版本至少为 0.5.3
2. ruff.nativeServer 设置被设为 auto（默认值）
3. 未启用任何专用于基于 Python 的语言服务器的设置（即 设置 文档中标记为“原生语言服务器未使用”的设置）。

你可以通过将 nativeServer 设置为 off 来选择不使用基于 Rust 的语言服务器。若设为 off，扩展将使用基于 Python 的语言服务器（ruff-lsp）。

{
  "ruff.nativeServer": "off"
}

你可以在 settings.json 中使用 ruff.lint.args 和 ruff.format.args 设置，向 Ruff 传递命令行参数。

例如，要在 VS Code 中启用 pyupgrade 规则集，请将以下内容添加到 settings.json：

{
  "ruff.lint.args": ["--extend-select=UP"]
}

若要完全覆盖 VS Code 扩展的 Ruff 配置，并覆盖任何本地 pyproject.toml 文件或类似文件，你可以通过 settings.json 中的 ruff.lint.args 和 ruff.format.args 选项，向 Ruff CLI 传递自定义的 --config 参数：

{
  "ruff.lint.args": ["--config=/path/to/ruff.toml"],
  "ruff.format.args": ["--config=/path/to/ruff.toml"]
}

最后，若要在所有项目中使用通用的 Ruff 配置，可考虑创建用户特定的 pyproject.toml 或 ruff.toml 文件，具体方法详见 常见问题解答。

命令

命令	描述
Ruff: Fix all auto-fixable problems	修复所有可自动修复的问题
Ruff: Format Imports	整理导入语句
Ruff: Format Document	格式化整个文档
Ruff: Restart Server	强制重启 linter 服务器
Ruff: Print debug information (native server only)	打印原生服务器的调试信息
Ruff: Show client logs	打开 Ruff 输出通道
Ruff: Show server logs	打开 Ruff 语言服务器输出通道

故障排除

如果您在使用扩展或语言服务器时遇到任何问题，请查看 VS Code 中相应输出通道的日志。扩展日志位于 “Ruff” 输出通道，语言服务器日志位于 “Ruff Language Server” 输出通道。

要打开输出面板，请在命令面板（Ctrl+Shift+P 或 Cmd+Shift+P）中使用 Output: Show Output Channels 命令，然后选择 “Ruff” 或 “Ruff Language Server”。或者，您可以使用 Ruff: Show client logs 和 Ruff: Show server logs 命令分别打开 “Ruff” 和 “Ruff Language Server” 输出通道。Ruff: Print debug information 命令可用于打印调试信息，其中可能包括当前打开文件的详细信息。

扩展的默认日志级别为 info，可通过输出面板右上角的设置图标进行更改。

语言服务器的默认日志级别为 info，可通过 settings.json 中的 ruff.logLevel 设置进行更改：

{
  "ruff.logLevel": "info"
}

通过在 settings.json 中设置 ruff.logFile，可以将语言服务器日志输出到文件：

{
  "ruff.logFile": "/path/to/ruff.log"
}

若要捕获编辑器与服务器之间的 LSP 消息，请在 settings.json 中将 ruff.trace.server 设置为 messages 或 verbose：

{
  "ruff.trace.server": "messages"
}

此内容将显示在“Ruff Language Server Trace”输出通道中。messages 和 verbose 的区别在于，messages 仅记录请求和响应的方法名称，而 verbose 还会记录客户端发送的请求参数以及服务器发送的响应结果。

扩展程序还会在状态栏中显示某些信息。这些信息可以固定在状态栏中，作为永久项。

如何在 VS Code 工具栏中固定 Ruff 状态项？

状态栏项会显示语言服务器的状态，具体来说是使用基于 Rust 的语言服务器（Ruff (native)）还是基于 Python 的语言服务器（Ruff (ruff-lsp)）。点击它还可以打开 Ruff 输出通道。

许可证

MIT