从 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迁移到原生服务器的过程通常包含以下全部或部分步骤将废弃设置deprecated settings迁移为新设置new settings**移除remove**不再受支持的设置更新ruff版本。理解设计差异为什么lint.args/format.args不再存在在动手改配置之前先理解原生服务器的底层设计差异迁移思路会更清晰。ruff-lsp本质上是一个包装器它拿到编辑器传过来的lint.args、format.args等字符串参数再把这些参数拼进 CLI 命令以子进程方式调用ruff check或ruff format。原生服务器则完全不同它把 Ruff 直接编译为 Rust 库并内嵌进 LSP 进程设置以结构化数据而非命令行字符串的形式传入。这在源码中有直接体现客户端设置被反序列化为ClientOptions结构体字段全部是类型化的OptionT见 crates/ruff_server/src/session/options.rspub(crate) struct ClientOptions { configuration: OptionClientConfiguration, fix_all: Optionbool, organize_imports: Optionbool, lint: OptionLintOptions, format: OptionFormatOptions, code_action: OptionCodeActionOptions, exclude: OptionVecString, line_length: OptionLineLength, configuration_preference: OptionConfigurationPreference, show_syntax_errors: Optionbool, }其中的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 附加命令行参数例如--selectE,F、--line-length 80等。它们已被原生服务器中更细粒度的设置取代例如 lint.select、format.preview 等任何无法用独立设置表达的配置都可以通过 configuration 设置覆盖。具体迁移方式见下文迁移示例一节。path与interpreter扩展仍在使用以下设置不被语言服务器接受但仍然被 [VS Code 扩展]使用迁移时不要盲目删除pathruff可执行文件的路径列表。第一个存在的可执行文件会被使用优先级高于importStrategy设置。interpreterPython 解释器路径列表虽然类型是列表但只使用第一个。其行为取决于nativeServer设置使用原生服务器时解释器用于在importStrategy为fromEnvironment时查找ruff可执行文件否则用于运行ruff-lsp服务器。它们的具体行为请参考各自文档由扩展负责消费与服务器本体无关。需要移除的设置Removed Settings以下设置在原生服务器中完全不被支持应当从配置中删除ignoreStandardLibrary旧版中用于忽略被推断为 Python 标准库一部分的文件。原生服务器不再需要它它自行处理文件归属保留该设置只会产生警告。showNotifications旧版中用于控制何时显示通知off/onError/onWarning/always。原生服务器使用 LSP 标准机制上报错误与日志该设置不再有效。新增设置New Settings原生服务器引入了一系列ruff-lsp所没有的新设置全部类型化、默认值明确可在编辑器 UI 中直接配置。各设置的默认值与含义如下设置默认值类型说明configurationnullstring0.9.8 起也支持对象指定ruff.toml/pyproject.toml路径或直接内联 JSON 配置内联方式在 Ruff0.9.8引入configurationPreferenceeditorFirsteditorFirst \| filesystemFirst \| editorOnly编辑器设置与工作区配置文件冲突时的优先级策略excludenullstring[]从 lint / format 中排除的文件模式列表如[**/tests/**]format.previewnullbool格式化时是否启用 Ruff 的 preview 模式lineLengthnullint供 linter 与 formatter 共同使用的行宽lint.selectnullstring[]默认启用的规则集如[E, F]lint.extendSelectnullstring[]在lint.select基础上追加启用的规则集lint.ignorenullstring[]默认禁用的规则如[E4, E7]lint.previewnullboollint 时是否启用 Ruff 的 preview 模式三源优先级编辑器里如何解析配置在编辑器中Ruff 支持三个配置来源按从高到低的优先级排列具体设置Specific settings编辑器中定义的单个设置如 lineLength、lint.selectconfiguration通过该字段提供的配置配置文件路径或内联配置对象配置文件Configuration file项目目录下的ruff.toml或pyproject.toml若存在。例如行宽同时在三个来源中都指定了Ruff 将使用 lineLength 设置中的值。如果configuration未设置默认行为与在命令行运行 Ruff 一致加载项目目录下的ruff.toml或pyproject.toml。这一优先级在源码中的落地点是EditorSettings结构体——其中所有来自编辑器的字段均为Option只有在编辑器确实设置了该字段时才覆盖基于文件的配置见 crates/ruff_server/src/session/settings.rspub(crate) struct EditorSettings { pub(super) configuration: OptionResolvedConfiguration, pub(super) lint_preview: Optionbool, pub(super) format_preview: Optionbool, pub(super) format_backend: OptionFormatBackend, pub(super) select: OptionVecUnresolvedRuleSelector, pub(super) extend_select: OptionVecUnresolvedRuleSelector, pub(super) ignore: OptionVecUnresolvedRuleSelector, pub(super) exclude: OptionVecString, pub(super) line_length: OptionLineLength, pub(super) configuration_preference: ConfigurationPreference, }configurationPreference的三种策略configurationPreference 控制编辑器提供的配置configuration与项目级配置文件并存时的优先级。对应枚举定义见 crates/ruff_server/src/session/options.rseditorFirst默认编辑器设置优先于工作区中的ruff.toml/pyproject.tomlfilesystemFirst工作区中的配置文件优先于编辑器设置editorOnly完全忽略配置文件只使用编辑器设置。configuration的两种形式与限制configuration 支持两种取值配置文件路径指向包含配置的ruff.toml或pyproject.toml路径支持用户主目录~与环境变量展开。源码中通过shellexpand::full完成展开见 crates/ruff_server/src/session/settings.rs内联 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: --selectE,F --unfixableF401 --unsafe-fixes }--selectE,F可以直接映射为 lint.select而--unfixableF401与--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 --configformat.quote-styledouble }--line-length 80可以映射为 lineLengthformat.quote-styledouble则通过 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
从 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迁移到原生服务器的过程通常包含以下全部或部分步骤将废弃设置deprecated settings迁移为新设置new settings**移除remove**不再受支持的设置更新ruff版本。理解设计差异为什么lint.args/format.args不再存在在动手改配置之前先理解原生服务器的底层设计差异迁移思路会更清晰。ruff-lsp本质上是一个包装器它拿到编辑器传过来的lint.args、format.args等字符串参数再把这些参数拼进 CLI 命令以子进程方式调用ruff check或ruff format。原生服务器则完全不同它把 Ruff 直接编译为 Rust 库并内嵌进 LSP 进程设置以结构化数据而非命令行字符串的形式传入。这在源码中有直接体现客户端设置被反序列化为ClientOptions结构体字段全部是类型化的OptionT见 crates/ruff_server/src/session/options.rspub(crate) struct ClientOptions { configuration: OptionClientConfiguration, fix_all: Optionbool, organize_imports: Optionbool, lint: OptionLintOptions, format: OptionFormatOptions, code_action: OptionCodeActionOptions, exclude: OptionVecString, line_length: OptionLineLength, configuration_preference: OptionConfigurationPreference, show_syntax_errors: Optionbool, }其中的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 附加命令行参数例如--selectE,F、--line-length 80等。它们已被原生服务器中更细粒度的设置取代例如 lint.select、format.preview 等任何无法用独立设置表达的配置都可以通过 configuration 设置覆盖。具体迁移方式见下文迁移示例一节。path与interpreter扩展仍在使用以下设置不被语言服务器接受但仍然被 [VS Code 扩展]使用迁移时不要盲目删除pathruff可执行文件的路径列表。第一个存在的可执行文件会被使用优先级高于importStrategy设置。interpreterPython 解释器路径列表虽然类型是列表但只使用第一个。其行为取决于nativeServer设置使用原生服务器时解释器用于在importStrategy为fromEnvironment时查找ruff可执行文件否则用于运行ruff-lsp服务器。它们的具体行为请参考各自文档由扩展负责消费与服务器本体无关。需要移除的设置Removed Settings以下设置在原生服务器中完全不被支持应当从配置中删除ignoreStandardLibrary旧版中用于忽略被推断为 Python 标准库一部分的文件。原生服务器不再需要它它自行处理文件归属保留该设置只会产生警告。showNotifications旧版中用于控制何时显示通知off/onError/onWarning/always。原生服务器使用 LSP 标准机制上报错误与日志该设置不再有效。新增设置New Settings原生服务器引入了一系列ruff-lsp所没有的新设置全部类型化、默认值明确可在编辑器 UI 中直接配置。各设置的默认值与含义如下设置默认值类型说明configurationnullstring0.9.8 起也支持对象指定ruff.toml/pyproject.toml路径或直接内联 JSON 配置内联方式在 Ruff0.9.8引入configurationPreferenceeditorFirsteditorFirst \| filesystemFirst \| editorOnly编辑器设置与工作区配置文件冲突时的优先级策略excludenullstring[]从 lint / format 中排除的文件模式列表如[**/tests/**]format.previewnullbool格式化时是否启用 Ruff 的 preview 模式lineLengthnullint供 linter 与 formatter 共同使用的行宽lint.selectnullstring[]默认启用的规则集如[E, F]lint.extendSelectnullstring[]在lint.select基础上追加启用的规则集lint.ignorenullstring[]默认禁用的规则如[E4, E7]lint.previewnullboollint 时是否启用 Ruff 的 preview 模式三源优先级编辑器里如何解析配置在编辑器中Ruff 支持三个配置来源按从高到低的优先级排列具体设置Specific settings编辑器中定义的单个设置如 lineLength、lint.selectconfiguration通过该字段提供的配置配置文件路径或内联配置对象配置文件Configuration file项目目录下的ruff.toml或pyproject.toml若存在。例如行宽同时在三个来源中都指定了Ruff 将使用 lineLength 设置中的值。如果configuration未设置默认行为与在命令行运行 Ruff 一致加载项目目录下的ruff.toml或pyproject.toml。这一优先级在源码中的落地点是EditorSettings结构体——其中所有来自编辑器的字段均为Option只有在编辑器确实设置了该字段时才覆盖基于文件的配置见 crates/ruff_server/src/session/settings.rspub(crate) struct EditorSettings { pub(super) configuration: OptionResolvedConfiguration, pub(super) lint_preview: Optionbool, pub(super) format_preview: Optionbool, pub(super) format_backend: OptionFormatBackend, pub(super) select: OptionVecUnresolvedRuleSelector, pub(super) extend_select: OptionVecUnresolvedRuleSelector, pub(super) ignore: OptionVecUnresolvedRuleSelector, pub(super) exclude: OptionVecString, pub(super) line_length: OptionLineLength, pub(super) configuration_preference: ConfigurationPreference, }configurationPreference的三种策略configurationPreference 控制编辑器提供的配置configuration与项目级配置文件并存时的优先级。对应枚举定义见 crates/ruff_server/src/session/options.rseditorFirst默认编辑器设置优先于工作区中的ruff.toml/pyproject.tomlfilesystemFirst工作区中的配置文件优先于编辑器设置editorOnly完全忽略配置文件只使用编辑器设置。configuration的两种形式与限制configuration 支持两种取值配置文件路径指向包含配置的ruff.toml或pyproject.toml路径支持用户主目录~与环境变量展开。源码中通过shellexpand::full完成展开见 crates/ruff_server/src/session/settings.rs内联 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: --selectE,F --unfixableF401 --unsafe-fixes }--selectE,F可以直接映射为 lint.select而--unfixableF401与--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 --configformat.quote-styledouble }--line-length 80可以映射为 lineLengthformat.quote-styledouble则通过 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
)
