跳到内容

设置

我们有针对您选择的编辑器的特定设置说明。如果您在此列表中没有看到您的编辑器，并且想要设置指南，请提出问题。

如果您正在从 ruff-lsp 迁移您的配置，无论使用何种编辑器，都有一些设置已更改或不再可用。请参阅迁移指南了解更多信息。

注意

以下提供的设置说明是尽最大努力的结果。如果您在编辑器中设置 Ruff 时遇到任何问题，请提出问题以获得帮助并帮助改进此文档。

提示

无论使用何种编辑器，建议禁用旧的语言服务器 (ruff-lsp)，以防止任何冲突。

VS Code

从 VS Code Marketplace 安装 Ruff 扩展。 建议使用 Ruff 扩展版本 2024.32.0 或更高版本，以获得 Ruff 语言服务器的最佳体验。

有关 Ruff 扩展的更多文档，请参阅扩展存储库的 README。

Neovim

nvim-lspconfig 插件可用于在 Neovim 中配置 Ruff 语言服务器。要进行设置，请安装 nvim-lspconfig 插件，按照配置文档进行设置，并将以下内容添加到您的 init.lua

require('lspconfig').ruff.setup({
  init_options = {
    settings = {
      -- Ruff language server settings go here
    }
  }
})

vim.lsp.config('ruff', {
  init_options = {
    settings = {
      -- Ruff language server settings go here
    }
  }
})

vim.lsp.enable('ruff')

注意

如果已安装的 nvim-lspconfig 版本包含来自 neovim/nvim-lspconfig@70d1c2c 的更改，您将需要使用 Ruff 版本 0.5.3 或更高版本。

如果您正在将 Ruff 与另一个语言服务器（如 Pyright）一起使用，您可能希望将某些功能（如 textDocument/hover）推迟到该语言服务器。

vim.api.nvim_create_autocmd("LspAttach", {
  group = vim.api.nvim_create_augroup('lsp_attach_disable_ruff_hover', { clear = true }),
  callback = function(args)
    local client = vim.lsp.get_client_by_id(args.data.client_id)
    if client == nil then
      return
    end
    if client.name == 'ruff' then
      -- Disable hover in favor of Pyright
      client.server_capabilities.hoverProvider = false
    end
  end,
  desc = 'LSP: Disable hover capability from Ruff',
})

如果您只想使用 Ruff 进行 linting、格式化和组织导入，您可以禁用 Pyright 的这些功能

require('lspconfig').pyright.setup {
  settings = {
    pyright = {
      -- Using Ruff's import organizer
      disableOrganizeImports = true,
    },
    python = {
      analysis = {
        -- Ignore all files for analysis to exclusively use Ruff for linting
        ignore = { '*' },
      },
    },
  },
}

默认情况下，Ruff 的日志级别设置为 info。要更改日志级别，您可以设置 logLevel 设置

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      logLevel = 'debug',
    }
  }
}

默认情况下，Ruff 会将日志写入 stderr，这些日志将在 Neovim 的 LSP 客户端日志文件（:lua vim.print(vim.lsp.get_log_path())）中可用。也可以使用 logFile 设置将这些日志转移到单独的文件中。

要查看 Neovim 和 Ruff 之间的跟踪日志，请将 Neovim 的 LSP 客户端的日志级别设置为 debug

vim.lsp.set_log_level('debug')
使用 Neovim 的 conform.nvim 插件。 
require("conform").setup({
    formatters_by_ft = {
        python = {
          -- To fix auto-fixable lint errors.
          "ruff_fix",
          -- To run the Ruff formatter.
          "ruff_format",
          -- To organize the imports.
          "ruff_organize_imports",
        },
    },
})
使用 Neovim 的 nvim-lint 插件。 
require("lint").linters_by_ft = {
  python = { "ruff" },
}
使用 Neovim 或 Vim 的 ALE 插件。 Neovim（使用 Lua） 
-- Linters
vim.g.ale_linters = { python = { "ruff" } }
-- Fixers
vim.g.ale_fixers = { python = { "ruff", "ruff_format" } }
Vim（使用 Vimscript） 
" Linters
let g:ale_linters = { "python": ["ruff"] }
" Fixers
let g:ale_fixers = { "python": ["ruff", "ruff_format"] }
对于 fixers，ruff 将运行 ruff check --fix（以修复所有可自动修复的问题），而 ruff_format 将运行 ruff format。

Vim

vim-lsp 插件可用于在 Vim 中配置 Ruff 语言服务器。要进行设置，请安装 vim-lsp 插件，并使用以下内容在您的 .vimrc 中注册服务器

if executable('ruff')
    au User lsp_setup call lsp#register_server({
        \ 'name': 'ruff',
        \ 'cmd': {server_info->['ruff', 'server']},
        \ 'allowlist': ['python'],
        \ 'workspace_config': {},
        \ })
endif

有关如何配置语言服务器的更多详细信息，请参阅 vim-lsp 文档。

如果您正在将 Ruff 与另一个 LSP（如 Pyright）一起使用，您可能希望将某些功能（如 textDocument/hover）推迟到该 LSP，方法是将以下内容添加到函数 s:on_lsp_buffer_enabled()

function! s:on_lsp_buffer_enabled() abort
    " add your keybindings here (see https://github.com/prabirshrestha/vim-lsp?tab=readme-ov-file#registering-servers)

    let l:capabilities = lsp#get_server_capabilities('ruff')
    if !empty(l:capabilities)
      let l:capabilities.hoverProvider = v:false
    endif
endfunction

Ruff 也作为 coc-pyright 扩展的一部分提供，适用于 coc.nvim。

Ruff 也可以通过 efm language server 集成，只需几行代码。以下是 efm 的示例配置，用于使用 Ruff 进行 linting 和格式化 Python 文件
tools:
  python-ruff:
    lint-command: "ruff check --stdin-filename ${INPUT} --output-format concise --quiet -"
    lint-stdin: true
    lint-formats:
      - "%f:%l:%c: %m"
    format-command: "ruff format --stdin-filename ${INPUT} --quiet -"
    format-stdin: true

Helix

打开 Helix 的语言配置文件，并按如下方式添加语言服务器

[language-server.ruff]
command = "ruff"
args = ["server"]

然后，您将注册该语言服务器作为与 Python 一起使用的服务器。如果您尚未注册任何语言服务器以与 Python 一起使用，请将其添加到 languages.toml

[[language]]
name = "python"
language-servers = ["ruff"]

否则，如果您已经定义了 language-servers，您可以简单地将 "ruff" 添加到列表中。例如，如果您已经有 pylsp 作为语言服务器，您可以按如下方式修改语言条目

[[language]]
name = "python"
language-servers = ["ruff", "pylsp"]

注意

对一种语言支持多个语言服务器仅在 Helix 版本 23.10 及更高版本中可用。

例如，如果您想启用自动格式化，请添加 auto-format = true

[[language]]
name = "python"
language-servers = ["ruff", "pylsp"]
auto-format = true

有关您可以在此处使用的更多设置，请参阅 Helix 文档。

您可以使用 [language-server.ruff.config.settings] 将设置传递到 ruff server。例如

[language-server.ruff.config.settings]
lineLength = 80

[language-server.ruff.config.settings.lint]
select = ["E4", "E7"]
preview = false

[language-server.ruff.config.settings.format]
preview = true

默认情况下，Ruff 的日志级别设置为 info。要更改日志级别，您可以设置 logLevel 设置

[language-server.ruff]
command = "ruff"
args = ["server"]

[language-server.ruff.config.settings]
logLevel = "debug"

您还可以使用 logFile 设置将 Ruff 的日志转移到单独的文件中。

要查看 Helix 和 Ruff 之间的跟踪日志，请在启动 Helix 时传入 -v（详细）标志

hx -v path/to/file.py

Kate

  1. 激活 LSP 客户端插件。
  2. 根据需要设置 LSP 客户端 。
  3. 最后，将其添加到 Settings -> Configure Kate -> LSP Client -> User Server Settings
{
  "servers": {
    "python": {
      "command": ["ruff", "server"],
      "url": "https://github.com/astral-sh/ruff",
      "highlightingModeRegex": "^Python$",
      "settings": {}
    }
  }
}

有关如何从那里配置服务器的更多详细信息，请参阅 LSP 客户端文档。

重要

Kate 的 LSP 客户端插件不支持同一语言的多个服务器。作为一种解决方法，您可以将 python-lsp-server 与 python-lsp-ruff 插件一起使用，以便将 Ruff 与另一个语言服务器一起使用。请注意，此设置不会使用服务器设置，因为 python-lsp-ruff 插件使用 ruff 可执行文件，而不是语言服务器。

Sublime Text

要将 Ruff 与 Sublime Text 一起使用，请安装 Sublime Text 的 LSP 和 LSP-ruff 包。

PyCharm

通过外部工具

Ruff 可以作为 PyCharm 中的外部工具安装。打开“Preferences”窗格，然后导航到“Tools”，然后导航到“External Tools”。从那里，添加一个具有以下配置的新工具

Install Ruff as an External Tool

然后，Ruff 应显示为可运行的操作

Ruff as a runnable action

通过第三方插件

Ruff 也可以在 IntelliJ Marketplace 上作为 Ruff 插件提供（由 @koxudaxi 维护）。

Emacs

Ruff 可以通过 Emacs 核心中的 Eglot 用作语言服务器。要在保存时启用带有自动格式的 Ruff，请使用以下配置

(add-hook 'python-mode-hook 'eglot-ensure)
(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               '(python-mode . ("ruff" "server")))
  (add-hook 'after-save-hook 'eglot-format))

Ruff 在 MELPA 上以 flymake-ruff 的形式提供

(require 'flymake-ruff)
(add-hook 'python-mode-hook #'flymake-ruff-load)

Ruff 也以 emacs-ruff-format 的形式提供

(require 'ruff-format)
(add-hook 'python-mode-hook 'ruff-format-on-save-mode)

或者，它可以通过 Apheleia 格式化程序库使用，方法是设置以下配置

;; Replace default (black) to use ruff for sorting import and formatting.
(setf (alist-get 'python-mode apheleia-mode-alist)
      '(ruff-isort ruff))
(setf (alist-get 'python-ts-mode apheleia-mode-alist)
      '(ruff-isort ruff))

TextMate

Ruff 也可以通过 TextMate 的 textmate2-ruff-linter 捆绑包使用。

Zed

Ruff 可以作为 Zed 编辑器的扩展使用。要安装它

  1. 使用 Cmd+Shift+P 打开命令面板
  2. 搜索“zed: extensions”
  3. 在扩展列表中搜索“ruff”，然后单击“安装”

要将 Zed 配置为对 Python 文件使用 Ruff 语言服务器，请将以下内容添加到您的 settings.json 文件

{
  "languages": {
    "Python": {
      "language_servers": ["ruff"]
      // Or, if there are other language servers you want to use with Python
      // "language_servers": ["pyright", "ruff"]
    }
  }
}

要配置语言服务器，您可以在 lsp.ruff.initialization_options.settings 键下提供服务器设置

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          // Ruff server settings goes here
          "lineLength": 80,
          "lint": {
            "extendSelect": ["I"],
          }
        }
      }
    }
  }
}

注意

对给定语言的多个格式化程序的支持仅在 Zed 版本 0.146.0 及更高版本中可用。

您可以通过注册 Ruff 格式化程序并启用 format_on_save 设置，将 Ruff 配置为在保存时格式化 Python 代码

{
  "languages": {
    "Python": {
      "language_servers": ["ruff"],
      "format_on_save": "on",
      "formatter": [
        {
          "language_server": {
            "name": "ruff"
          }
        }
      ]
    }
  }
}

您可以通过分别启用 source.fixAll.ruff 和 source.organizeImports.ruff 代码操作，将 Ruff 配置为在保存时修复 lint 违规和/或组织导入

{
  "languages": {
    "Python": {
      "language_servers": ["ruff"],
      "format_on_save": "on",
      "formatter": [
        {
          "code_actions": {
            // Fix all auto-fixable lint violations
            "source.fixAll.ruff": true,
            // Organize imports
            "source.organizeImports.ruff": true
          }
        }
      ]
    }
  }
}

综上所述，您可以通过以下 settings.json 配置 Ruff 以在保存时进行格式化、修复和组织导入

注意

对于此配置，重要的是使用代码操作和格式化程序语言服务器设置的正确顺序。代码操作应在格式化程序之前定义，以确保格式化程序在应用代码操作后处理任何剩余的样式问题。

{
  "languages": {
    "Python": {
      "language_servers": ["ruff"],
      "format_on_save": "on",
      "formatter": [
        {
          "code_actions": {
            "source.organizeImports.ruff": true,
            "source.fixAll.ruff": true
          }
        },
        {
          "language_server": {
            "name": "ruff"
          }
        }
      ]
    }
  }
}