设置

Ruff 语言服务器提供了一组配置选项来定制其行为，并支持使用现有的 pyproject.toml 或 ruff.toml 文件来配置检查器（linter）和格式化程序（formatter）。这可以通过在初始化服务器时提供这些设置来实现。VS Code 提供了用于配置这些设置的 UI，而其他编辑器可能需要手动配置。安装章节提供了关于如何根据不同编辑器放置这些设置的说明。

顶层

`配置`

configuration 设置允许你配置编辑器特定的 Ruff 行为。可以通过以下方式之一完成：

配置文件路径：指定包含配置的 ruff.toml 或 pyproject.toml 文件的路径。用户主目录和环境变量将被展开。
内联 JSON 配置：直接以 JSON 对象的形式提供配置。

于 Ruff 0.9.8 新增

内联 JSON 配置选项是在 Ruff 0.9.8 中引入的。

如果未设置 configuration，默认行为是加载项目配置（项目目录中的 ruff.toml 或 pyproject.toml），这与在命令行运行 Ruff 时保持一致。

如果同时存在编辑器提供的配置 (configuration) 和项目级配置文件，configurationPreference 设置将控制优先级。

解析顺序

在编辑器中，Ruff 支持三种配置来源，优先级如下（从高到低）：

特定设置：在编辑器中定义的独立设置，例如 lineLength 或 lint.select
ruff.configuration：通过 configuration 字段提供的设置（无论是配置文件路径还是内联配置对象）
配置文件：项目中 ruff.toml 或 pyproject.toml 文件中定义的设置（如果存在）

例如，如果所有三个来源都指定了行长度，Ruff 将使用 lineLength 设置中的值。

默认值: null

类型：string

用法示例:

使用配置文件路径

VS CodeNeovimZed

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

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      configuration = "~/path/to/ruff.toml"
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "configuration": "~/path/to/ruff.toml"
        }
      }
    }
  }
}

使用内联配置

VS CodeNeovimZed

{
    "ruff.configuration": {
        "lint": {
            "unfixable": ["F401"],
            "extend-select": ["TID251"],
            "flake8-tidy-imports": {
                "banned-api": {
                    "typing.TypedDict": {
                        "msg": "Use `typing_extensions.TypedDict` instead",
                    }
                }
            }
        },
        "format": {
            "quote-style": "single"
        }
    }
}

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      configuration = {
        lint = {
          unfixable = {"F401"},
          ["extend-select"] = {"TID251"},
          ["flake8-tidy-imports"] = {
            ["banned-api"] = {
              ["typing.TypedDict"] = {
                msg = "Use `typing_extensions.TypedDict` instead"
              }
            }
          }
        },
        format = {
          ["quote-style"] = "single"
        }
      }
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "configuration": {
            "lint": {
              "unfixable": ["F401"],
              "extend-select": ["TID251"],
              "flake8-tidy-imports": {
                "banned-api": {
                  "typing.TypedDict": {
                    "msg": "Use `typing_extensions.TypedDict` instead"
                  }
                }
              }
            },
            "format": {
              "quote-style": "single"
            }
          }
        }
      }
    }
  }
}

`configurationPreference`

在 VS Code 和文件系统之间解析设置时使用的策略。默认情况下，编辑器配置的优先级高于 ruff.toml 和 pyproject.toml 文件。

"editorFirst"：编辑器设置的优先级高于工作区中的配置文件。
"filesystemFirst"：工作区中配置文件的优先级高于编辑器设置。
"editorOnly"：完全忽略配置文件，即仅使用编辑器设置。

默认值："editorFirst"

类型："editorFirst" | "filesystemFirst" | "editorOnly"

用法示例:

VS CodeNeovimZed

{
    "ruff.configurationPreference": "filesystemFirst"
}

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      configurationPreference = "filesystemFirst"
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "configurationPreference": "filesystemFirst"
        }
      }
    }
  }
}

`exclude`

排除在检查和格式化之外的文件模式列表。详情请参阅文档。

默认值: null

类型：string[]

用法示例:

VS CodeNeovimZed

{
    "ruff.exclude": ["**/tests/**"]
}

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      exclude = ["**/tests/**"]
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "exclude": ["**/tests/**"]
        }
      }
    }
  }
}

`lineLength`

检查器和格式化程序使用的行长度。

默认值: null

类型: int

用法示例:

VS CodeNeovimZed

{
    "ruff.lineLength": 100
}

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      lineLength = 100
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "lineLength": 100
        }
      }
    }
  }
}

`fixAll`

是否将服务器注册为能够处理 source.fixAll 代码操作。

默认值: true

类型: bool

用法示例:

VS CodeNeovimZed

{
    "ruff.fixAll": false
}

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      fixAll = false
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "fixAll": false
        }
      }
    }
  }
}

`organizeImports`

是否将服务器注册为能够处理 source.organizeImports 代码操作。

默认值: true

类型: bool

用法示例:

VS CodeNeovimZed

{
    "ruff.organizeImports": false
}

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      organizeImports = false
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "organizeImports": false
        }
      }
    }
  }
}

`showSyntaxErrors`

Ruff v0.5.0 新增

是否显示语法错误诊断信息。

默认值: true

类型: bool

用法示例:

VS CodeNeovimZed

{
    "ruff.showSyntaxErrors": false
}

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      showSyntaxErrors = false
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "showSyntaxErrors": false
        }
      }
    }
  }
}

`logLevel`

服务器使用的日志级别。

默认值："info"

类型："trace" | "debug" | "info" | "warn" | "error"

用法示例:

VS CodeNeovimZed

{
    "ruff.logLevel": "debug"
}

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

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "logLevel": "debug"
        }
      }
    }
  }
}

`logFile`

服务器使用的日志文件路径。

如果未设置，日志将写入 stderr。

默认值: null

类型：string

用法示例:

VS CodeNeovimZed

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

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      logFile = "~/path/to/ruff.log"
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "logFile": "~/path/to/ruff.log"
        }
      }
    }
  }
}

`codeAction`

启用或禁用服务器提供的代码操作。

`disableRuleComment.enable`

是否显示通过 noqa 抑制注释来禁用规则的快速修复（Quick Fix）操作。

默认值: true

类型: bool

用法示例:

VS CodeNeovimZed

{
    "ruff.codeAction.disableRuleComment.enable": false
}

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      codeAction = {
        disableRuleComment = {
          enable = false
        }
      }
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "codeAction": {
            "disableRuleComment": {
              "enable": false
            }
          }
        }
      }
    }
  }
}

`fixViolation.enable`

是否显示用于自动修复违规问题的快速修复操作。

默认值: true

类型: bool

用法示例:

VS CodeNeovimZed

{
    "ruff.codeAction.fixViolation.enable": false
}

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      codeAction = {
        fixViolation = {
          enable = false
        }
      }
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "codeAction": {
            "fixViolation": = {
              "enable": false
            }
          }
        }
      }
    }
  }
}

`lint`

Ruff 检查器特有的设置。

`enable`

是否启用检查。设置为 false 可使 Ruff 仅作为格式化程序使用。

默认值: true

类型: bool

用法示例:

VS CodeNeovimZed

{
    "ruff.lint.enable": false
}

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      lint = {
        enable = false
      }
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "lint": {
            "enable": false
          }
        }
      }
    }
  }
}

`preview`

检查时是否启用 Ruff 的预览模式。

默认值: null

类型: bool

用法示例:

VS CodeNeovimZed

{
    "ruff.lint.preview": true
}

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      lint = {
        preview = true
      }
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "lint": {
            "preview": true
          }
        }
      }
    }
  }
}

`select`

默认启用的规则。请参阅文档。

默认值: null

类型：string[]

用法示例:

VS CodeNeovimZed

{
    "ruff.lint.select": ["E", "F"]
}

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      lint = {
        select = {"E", "F"}
      }
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "lint": {
            "select": ["E", "F"]
          }
        }
      }
    }
  }
}

`extendSelect`

在 lint.select 基础上额外启用的规则。

默认值: null

类型：string[]

用法示例:

VS CodeNeovimZed

{
    "ruff.lint.extendSelect": ["W"]
}

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      lint = {
        extendSelect = {"W"}
      }
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "lint": {
            "extendSelect": ["W"]
          }
        }
      }
    }
  }
}

`ignore`

默认禁用的规则。请参阅文档。

默认值: null

类型：string[]

用法示例:

VS CodeNeovimZed

{
    "ruff.lint.ignore": ["E4", "E7"]
}

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      lint = {
        ignore = {"E4", "E7"}
      }
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "lint": {
            "ignore": ["E4", "E7"]
          }
        }
      }
    }
  }
}

`format`

Ruff 格式化程序特有的设置。

`preview`

格式化时是否启用 Ruff 的预览模式。

默认值: null

类型: bool

用法示例:

VS CodeNeovimZed

{
    "ruff.format.preview": true
}

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      format = {
        preview = true
      }
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "format": {
            "preview": true
          }
        }
      }
    }
  }
}

`backend`

用于文件格式化的后端。提供以下选项：

"internal"：使用 Ruff 内置格式化程序
"uv"：使用 uv 进行格式化（需要 uv >= 0.8.13）

对于 internal，格式化程序版本将与选定的 Ruff 版本匹配；而对于 uv，格式化程序版本可能有所不同。

默认值："internal"

类型："internal" | "uv"

用法示例:

VS CodeNeovimZed

{
    "ruff.format.backend": "uv"
}

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      format = {
        backend = "uv"
      }
    }
  }
}

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "format": {
            "backend": "uv"
          }
        }
      }
    }
  }
}

VS Code 特有

此外，Ruff 扩展提供了以下特定于 VS Code 的设置。这些设置不由语言服务器使用，仅与扩展相关。

`enable`

是否启用 Ruff 扩展。修改此设置需要重启 VS Code 才能生效。

默认值: true

类型: bool

用法示例:

{
    "ruff.enable": false
}

`format.args`

已弃用

此设置仅由 ruff-lsp 使用，该项目已被原生语言服务器取代。更多信息请参考迁移指南。

此设置不由原生语言服务器使用。

传递给 Ruff 格式化程序的额外参数。

默认值: []

类型：string[]

用法示例:

{
    "ruff.format.args": ["--line-length", "100"]
}

`ignoreStandardLibrary`

已弃用

此设置仅由 ruff-lsp 使用，该项目已被原生语言服务器取代。更多信息请参考迁移指南。

此设置不由原生语言服务器使用。

是否忽略被推断为 Python 标准库一部分的文件。

默认值: true

类型: bool

用法示例:

{
    "ruff.ignoreStandardLibrary": false
}

`importStrategy`

加载 ruff 可执行文件的策略。

fromEnvironment 在环境中查找 Ruff，如果找不到则回退到捆绑版本
useBundled 使用扩展捆绑的版本

默认值："fromEnvironment"

类型："fromEnvironment" | "useBundled"

用法示例:

{
    "ruff.importStrategy": "useBundled"
}

`interpreter`

Python 解释器路径列表。尽管这是一个列表，但仅使用第一个解释器。

此设置取决于 ruff.nativeServer 设置。

如果使用原生服务器，当 ruff.importStrategy 设置为 fromEnvironment 时，该解释器用于查找 ruff 可执行文件。
否则，该解释器用于运行 ruff-lsp 服务器。

默认值: []

类型：string[]

用法示例:

{
    "ruff.interpreter": ["/home/user/.local/bin/python"]
}

`lint.args`

已弃用

此设置仅由 ruff-lsp 使用，该项目已被原生语言服务器取代。更多信息请参考迁移指南。

此设置不由原生语言服务器使用。

传递给 Ruff 检查器的额外参数。

默认值: []

类型：string[]

用法示例:

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

`lint.run`

已弃用

此设置仅由 ruff-lsp 使用，该项目已被原生语言服务器取代。更多信息请参考迁移指南。

此设置不由原生语言服务器使用。

在每次按键时 (onType) 或保存时 (onSave) 运行 Ruff。

默认值："onType"

类型："onType" | "onSave"

用法示例:

{
    "ruff.lint.run": "onSave"
}

`nativeServer`

是否使用原生语言服务器 ruff-lsp，还是根据 Ruff 版本和扩展设置自动决定。

"on"：使用原生语言服务器。如果检测到已弃用的设置，将显示警告。
"off"：使用 ruff-lsp。如果检测到特定于原生服务器的设置，将显示警告。
"auto"：根据以下条件在原生语言服务器和 ruff-lsp 之间自动选择：
1. 如果 Ruff 版本 >= 0.5.3，使用原生语言服务器，除非检测到任何已弃用的设置。在这种情况下，显示警告并改用 ruff-lsp。
2. 如果 Ruff 版本 < 0.5.3，使用 ruff-lsp。如果检测到特定于原生服务器的设置，将显示警告。
true：与 on 相同
false：与 off 相同

默认值："auto"

类型："on" | "off" | "auto" | true | false

用法示例:

{
    "ruff.nativeServer": "on"
}

`path`

ruff 可执行文件的路径列表。

使用列表中第一个存在的可执行文件。此设置的优先级高于 ruff.importStrategy 设置。

默认值: []

类型：string[]

用法示例:

{
    "ruff.path": ["/home/user/.local/bin/ruff"]
}

`showNotifications`

已弃用

此设置仅由 ruff-lsp 使用，该项目已被原生语言服务器取代。更多信息请参考迁移指南。

控制何时显示通知的设置。

默认值："off"

类型："off" | "onError" | "onWarning" | "always"

用法示例:

{
    "ruff.showNotifications": "onWarning"
}

`trace.server`

语言服务器的跟踪级别。更多信息请参考 LSP 规范。

默认值："off"

类型："off" | "messages" | "verbose"

用法示例:

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