设置

Ruff 语言服务器提供了一系列配置选项来自定义其行为，并且能够使用现有的 pyproject.toml 或 ruff.toml 文件来配置 linter 和格式化程序。这可以通过在初始化服务器时提供这些设置来完成。 VS Code 提供了一个 UI 来配置这些设置，而其他编辑器可能需要手动配置。 设置部分提供了有关在哪里放置这些设置的说明，具体取决于编辑器。

顶层

配置

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

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

在 Ruff 0.9.8 中添加

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

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

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

解析顺序

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

1. 特定设置：在编辑器中定义的各个设置，如 lineLength 或 lint.select
2. ruff.configuration：通过 configuration 字段提供的设置（配置文件的路径或内联配置对象）
3. 配置文件：在项目目录中的 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

要从 linting 和格式化中排除的文件模式列表。 有关更多详细信息，请参见 文档。

默认值: null

类型: string[]

用法示例:

VS CodeNeovimZed

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

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

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

lineLength

用于 linter 和格式化程序的行长度。

默认值: 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 抑制注释禁用规则。

默认值: 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 linter 的设置。

enable

是否启用 linting。 设置为 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

是否在 linting 时启用 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
          }
        }
      }
    }
  }
}

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 linter 的其他参数。

默认值: []

类型: 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"
}