企业官网建设流程全解析

从 ruff-lsp 迁移到 Ruff 原生语言服务器：编辑器设置迁移完整指南

【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff

本篇指南围绕 Ruff 原生语言服务器（native server，即ruff server命令）与旧版ruff-lsp之间的配置体系差异展开，面向所有使用 VS Code、Neovim、Zed 等编辑器的开发者。读完本文，你将掌握迁移的完整步骤：识别不支持的旧设置、移除失效设置、掌握configuration、lint.select、lineLength等新增设置的正确用法，并通过可复制的 JSON / Lua 示例完成三种常见场景（配置文件、lint.args、format.args）的无痛迁移。

为什么需要迁移：ruff-lsp与原生服务器的区别

ruff-lsp是 Ruff 的 Language Server Protocol 实现，用 Python 编写，是独立于 Ruff 本身的单独包。而**原生服务器（native server）**则是用Rust编写、内置于 Ruff 二进制中的 LSP 实现，通过ruff server命令直接启动，随 Ruff 版本一起分发，无需单独安装 Python 包。

从版本演进看：

• 原生服务器在 Ruff0.3.5中首次引入；
• 在0.4.5中标记为 beta；
• 在0.5.3中正式稳定（stabilized）。

为了获得最好的使用体验，官方建议使用最新版本的 Ruff。从ruff-lsp迁移到原生服务器的过程通常包含以下全部或部分步骤：

1. 将废弃设置（deprecated settings）迁移为新设置（new settings）；
2. **移除（remove）**不再受支持的设置；
3. 更新ruff版本。

理解设计差异：为什么lint.args/format.args不再存在

在动手改配置之前，先理解原生服务器的底层设计差异，迁移思路会更清晰。ruff-lsp本质上是一个"包装器"：它拿到编辑器传过来的lint.args、format.args等字符串参数，再把这些参数拼进 CLI 命令，以子进程方式调用ruff check或ruff format。

原生服务器则完全不同：它把 Ruff 直接编译为 Rust 库并内嵌进 LSP 进程，设置以结构化数据而非命令行字符串的形式传入。这在源码中有直接体现：客户端设置被反序列化为ClientOptions结构体，字段全部是类型化的Option<T>（见 crates/ruff_server/src/session/options.rs）：

pub(crate) struct ClientOptions { configuration: Option<ClientConfiguration>, fix_all: Option<bool>, organize_imports: Option<bool>, lint: Option<LintOptions>, format: Option<FormatOptions>, code_action: Option<CodeActionOptions>, exclude: Option<Vec<String>>, line_length: Option<LineLength>, configuration_preference: Option<ConfigurationPreference>, show_syntax_errors: Option<bool>, }

其中的LintOptions与FormatOptions只包含结构化字段（如select、extend_select、ignore、preview、backend），根本没有args这类自由字符串入口。这意味着：

• 所有--xxx风格的 CLI 参数都失去了意义，必须拆解为对应的结构化设置；
• 无法映射为独立设置的选项，统一通过configuration设置（指向配置文件或内联配置对象）承载。

同时，原生服务器默认每次按键（every keystroke）都会运行lint 检查，因此旧版中控制"运行时机的lint.run设置也不再相关。

不支持的设置（Unsupported Settings）

以下是原生服务器不支持的ruff-lsp设置，需要迁移或删除：

lint.run

该设置此前用于控制 Ruff 何时运行（onType每次按键 /onSave保存时）。原生服务器默认在每次按键时运行 lint，因此该设置不再相关，直接删除即可。对应文档见 docs/editors/settings.md。

lint.args与format.args

这两个设置此前用于给 linter / formatter 附加命令行参数，例如--select=E,F、--line-length 80等。它们已被原生服务器中更细粒度的设置取代，例如 lint.select、format.preview 等；任何无法用独立设置表达的配置，都可以通过 configuration 设置覆盖。具体迁移方式见下文"迁移示例"一节。

path与interpreter（扩展仍在使用）

以下设置不被语言服务器接受，但仍然被 [VS Code 扩展]使用，迁移时不要盲目删除：

• path：ruff可执行文件的路径列表。第一个存在的可执行文件会被使用，优先级高于importStrategy设置。
• interpreter：Python 解释器路径列表（虽然类型是列表，但只使用第一个）。其行为取决于nativeServer设置：使用原生服务器时，解释器用于在importStrategy为fromEnvironment时查找ruff可执行文件；否则用于运行ruff-lsp服务器。

它们的具体行为请参考各自文档，由扩展负责消费，与服务器本体无关。

需要移除的设置（Removed Settings）

以下设置在原生服务器中完全不被支持，应当从配置中删除：

• ignoreStandardLibrary：旧版中用于"忽略被推断为 Python 标准库一部分的文件"。原生服务器不再需要它（它自行处理文件归属），保留该设置只会产生警告。
• showNotifications：旧版中用于控制何时显示通知（off/onError/onWarning/always）。原生服务器使用 LSP 标准机制上报错误与日志，该设置不再有效。

新增设置（New Settings）

原生服务器引入了一系列ruff-lsp所没有的新设置，全部类型化、默认值明确，可在编辑器 UI 中直接配置。各设置的默认值与含义如下：

三源优先级：编辑器里如何解析配置

在编辑器中，Ruff 支持三个配置来源，按从高到低的优先级排列：

1. 具体设置（Specific settings）：编辑器中定义的单个设置，如 lineLength、lint.select；
2. configuration：通过该字段提供的配置（配置文件路径或内联配置对象）；
3. 配置文件（Configuration file）：项目目录下的ruff.toml或pyproject.toml（若存在）。

例如行宽同时在三个来源中都指定了，Ruff 将使用 lineLength 设置中的值。如果configuration未设置，默认行为与在命令行运行 Ruff 一致：加载项目目录下的ruff.toml或pyproject.toml。

这一优先级在源码中的落地点是EditorSettings结构体——其中所有来自编辑器的字段均为Option，只有在编辑器确实设置了该字段时才覆盖基于文件的配置（见 crates/ruff_server/src/session/settings.rs）：

pub(crate) struct EditorSettings { pub(super) configuration: Option<ResolvedConfiguration>, pub(super) lint_preview: Option<bool>, pub(super) format_preview: Option<bool>, pub(super) format_backend: Option<FormatBackend>, pub(super) select: Option<Vec<UnresolvedRuleSelector>>, pub(super) extend_select: Option<Vec<UnresolvedRuleSelector>>, pub(super) ignore: Option<Vec<UnresolvedRuleSelector>>, pub(super) exclude: Option<Vec<String>>, pub(super) line_length: Option<LineLength>, pub(super) configuration_preference: ConfigurationPreference, }

configurationPreference的三种策略

configurationPreference 控制"编辑器提供的配置（configuration）"与"项目级配置文件"并存时的优先级。对应枚举定义见 crates/ruff_server/src/session/options.rs：

• "editorFirst"（默认）：编辑器设置优先于工作区中的ruff.toml/pyproject.toml；
• "filesystemFirst"：工作区中的配置文件优先于编辑器设置；
• "editorOnly"：完全忽略配置文件，只使用编辑器设置。

configuration的两种形式与限制

configuration 支持两种取值：

1. 配置文件路径：指向包含配置的ruff.toml或pyproject.toml，路径支持用户主目录（~）与环境变量展开。源码中通过shellexpand::full完成展开（见 crates/ruff_server/src/session/settings.rs）；
2. 内联 JSON 配置：直接以 JSON 对象提供配置（Ruff0.9.8起支持）。源码中内联配置会被序列化为 TOML 表，再经由Options::from_toml_table解析为正式的 Ruff 配置（见 crates/ruff_server/src/session/settings.rs）。

内联配置有一个明确的限制：不支持extend字段。源码中遇到extend会直接报出ExtendNotSupported错误，其余字段则按 Ruff 配置架构正常解析。此外，编辑器直接提供的规则选择器（select/extendSelect/ignore）会被标记为ValueSource::Editor来源，以便在规则不存在时给出"来自编辑器配置"的明确报错（见 crates/ruff_server/src/session/options.rs）。

迁移示例

以下示例均以VS Code 扩展的 JSON 配置格式演示；其他编辑器（Neovim、Zed 等）请参照 settings 页面中各自的位置说明放置，setup 一节提供了各编辑器下设置的具体存放位置。

示例一：配置文件迁移

如果你之前通过ruff.lint.args和ruff.format.args同时给 linter 与 formatter 指定同一个自定义配置文件：

{ "ruff.lint.args": "--config ~/.config/custom_ruff_config.toml", "ruff.format.args": "--config ~/.config/custom_ruff_config.toml" }

迁移到原生服务器后，只需使用 configuration 设置，一份配置同时作用于 linter 和 formatter：

{ "ruff.configuration": "~/.config/custom_ruff_config.toml" }

Neovim 中的等价写法（通过init_options.settings传入）：

vim.lsp.config('ruff', { init_options = { settings = { configuration = "~/.config/custom_ruff_config.toml" } } })

示例二：lint.args迁移

如果你此前用ruff.lint.args传入 linter 参数：

{ "ruff.lint.args": "--select=E,F --unfixable=F401 --unsafe-fixes" }

--select=E,F可以直接映射为 lint.select；而--unfixable=F401与--unsafe-fixes没有对应的独立编辑器设置，需要通过 configuration 以 Ruff 配置语义提供：

{ "ruff.lint.select": ["E", "F"], "ruff.configuration": { "unsafe-fixes": true, "lint": { "unfixable": ["F401"] } } }

迁移后请注意以下分工规则：

• 以下选项可以直接在编辑器设置中配置：lint.select、lint.extendSelect、lint.ignore、lint.preview；
• 其余选项通过 configuration 设置提供。

示例三：format.args迁移

如果你此前用ruff.format.args传入 formatter 参数：

{ "ruff.format.args": "--line-length 80 --config='format.quote-style=double'" }

--line-length 80可以映射为 lineLength；format.quote-style=double则通过 configuration 以内联配置的形式提供：

{ "ruff.lineLength": 80, "ruff.configuration": { "format": { "quote-style": "double" } } }

同样遵循分工规则：

• 以下选项可以直接在编辑器设置中配置：lineLength、format.preview；
• 其余选项通过 configuration 设置提供。

内联配置同样支持更复杂的结构，例如同时配置 lint 规则、插件参数与格式化风格：

{ "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" } } }

升级与验证

完成设置迁移后，请将ruff更新到最新版本（原生服务器在0.5.3稳定，内联configuration需要0.9.8及以上，新功能持续演进）。如果你使用的是 VS Code 扩展，可以显式将 nativeServer 设为"on"，此时若检测到废弃设置，扩展会给出警告提示；也可保持默认的"auto"，由扩展根据 Ruff 版本（>=0.5.3且未检测到废弃设置时）自动启用原生服务器。

排查问题时，可通过 logLevel（默认"info"，可选"trace"/"debug"/"warn"/"error"）与 logFile（默认写入 stderr）开启详细日志；服务器收到无效设置时，会向客户端弹出错误提示并回退到部分有效的设置（相关逻辑见 crates/ruff_server/src/session/settings.rs）。

需要留意的是，迁移后旧版 format.args、lint.args、lint.run、ignoreStandardLibrary、showNotifications 这些设置不再被原生服务器使用（部分仍被扩展消费），文档中均标注为废弃并指向本迁移指南。将这些设置逐条对照本文的"不支持 / 移除 / 新增"清单清理干净，即可让原生服务器以全新、结构化的配置体系稳定运行。

【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff