Pyright 语言服务器设置详解：pyright 与 python.analysis 配置项全解及源码级解析

Pyright 语言服务器设置详解pyright 与 python.analysis 配置项全解及源码级解析【免费下载链接】pyrightStatic Type Checker for Python项目地址: https://gitcode.com/GitHub_Trending/py/pyrightPyright 作为 VS Code 中的 Python 语言服务器除了解析项目配置文件外还会读取并合并一组独立的编辑器设置。本文基于仓库文档docs/settings.md完整覆盖 Pyright 语言服务器当前认可的全部设置项pyright.*、python.analysis.*、python.*三大类并结合packages/pyright-internal/src/server.ts等源码说明每项设置的默认值、解析顺序与生效机制帮助你正确配置类型检查级别、诊断范围、解释器环境与导入搜索路径。设置从哪里来配置来源与优先级Pyright 的语言服务器启动后通过 LSP 的workspace/configuration请求从客户端拉取设置。在 VS Code 中这些设置来自settings.json用户级或工作区级。getSettings方法的实现位于 server.ts第 95224 行其读取顺序值得注意先读python配置段包括python.pythonPath、python.venvPath和python.analysis.*子段再读pyright配置段其中openFilesOnly、useLibraryCodeForTypes、typeCheckingMode这几个旧命名项会覆盖前面从python.analysis读到的值源码中pyrightSection的处理逻辑位于 server.ts。也就是说当同时存在python.analysis.typeCheckingMode和旧名pyright.typeCheckingMode时旧名生效——这也解释了文档中“旧名已弃用但仍被认可deprecated but still currently honored”的说明。另一个关键前提是配置文件的存在与否根据 configuration.md 中 “Overriding settings (in VS Code)” 一节的说明如果工作区存在pyrightconfig.json或带pyright段的pyproject.toml那么 VS Codesettings.json中的 pyright 设置会被忽略只有在项目配置文件不存在时本文所述的编辑器设置才参与生效。这与各设置项文档中反复出现的 “This can be overridden in the configuration file” 相呼应——项目配置文件pyrightconfig.json/pyproject.toml中的include、exclude、ignore、extraPaths等条目优先级高于python.analysis.*对应设置。pyright.* 前缀设置控制语言服务行为以下三项是 Pyright 独有的pyright.*前缀设置控制编辑器交互行为而非类型检查本身。pyright.disableLanguageServicesboolean禁用全部语言服务包括 hover 文本、补全、签名帮助、跳转定义、查找引用等。适用于“只用 Pyright 做类型检查、语言服务交给其他 Python 语言服务器”的场景。从源码结构看该标志在 languageServerBase.ts 中被写入workspace.disableLanguageServices随后每个语言服务入口onHover、onCompletion、onSignatureHelp、getDefinitions、onReferences、onDocumentSymbol等都会先检查该标志命中即直接返回空结果。注意类型检查诊断不受影响禁用的只是交互式语言功能。pyright.disableOrganizeImportsboolean禁用 “Organize Imports” 命令。当你使用其他扩展提供相似功能如 isort 扩展时可用此设置避免两个扩展互相冲突。其标志同样在 languageServerBase.ts 写入 workspace供代码动作Code Action提供者判断是否提供整理导入项。pyright.disableTaggedHintsboolean禁用带特殊 Diagnostic Tag 的“提示类”诊断。这些 tag 用于指示客户端以特定样式渲染文本范围Unnecessarytag将文本范围显示为灰色grayed out表示不可达代码或未引用符号Deprecatedtag将文本范围显示为删除线strikethrough表示使用了已弃用的特性。此外这些 tag 是否实际生效还取决于客户端能力协商languageServerBase.ts 在initialize阶段从客户端publishDiagnostics.tagSupport.valueSet中检测supportsUnnecessaryDiagnosticTag与supportsDeprecatedDiagnosticTag两者需同时满足才会输出对应 tag。已弃用pyright.openFilesOnly 与 pyright.useLibraryCodeForTypespyright.openFilesOnlyboolean决定 Pyright 是分析整个工作区还是仅分析打开的文件。此设置已弃用改用python.analysis.diagnosticMode文档注明“将在未来移除It will be removed at a future time”。从 server.ts 可见它仍会覆盖python.analysis段的值。pyright.useLibraryCodeForTypesboolean已弃用改用python.analysis.useLibraryCodeForTypes见下文。python.analysis.* 前缀设置核心功能配置python.analysis.typeCheckingModeoff | basic | standard | strict确定 Pyright 默认使用的类型检查级别。四个级别对应不同的内置诊断规则集默认值为standard。该设置的校验与规则集选择在 configOptions.ts 中实现配置值必须是off/basic/standard/strict之一否则报错Config typeCheckingMode entry must contain off, basic, standard, or strict.具体规则集由getDiagnosticRuleSet返回。设为off时所有类型检查规则关闭但 Python 语法错误与语义错误仍会报告。文档同时注明该设置旧名为pyright.typeCheckingMode旧名已弃用但当前仍被认可。各规则集包含的具体规则及默认值参见 configuration.md 的 “Type Check Diagnostics Settings” 一节单个reportXXX规则可用python.analysis.diagnosticSeverityOverrides或配置文件中的对应条目覆盖。python.analysis.diagnosticModeopenFilesOnly | workspace决定 Pyright 分析并报告错误的范围openFilesOnly仅分析已打开的文件workspace分析配置文件所指示的工作区内所有文件。从 server.ts 的解析逻辑看判断收敛在isOpenFilesOnly(diagnosticMode)函数中languageServerBase.tsdiagnosticMode ! workspace即为 open-files-only 模式。且解析顺序上diagnosticMode优先于旧设置openFilesOnly——只有当diagnosticMode未定义时才回退到openFilesOnly的值。该模式最终映射为checkOnlyOpenFiles命令行选项见 analyzerServiceExecutor.ts。python.analysis.diagnosticSeverityOverridesmap允许用户对单个诊断规则的严重级别进行覆盖。键为规则名reportXXX形式的 type check diagnostics 规则支持范围见 configuration.md值可以是error/truewarninginformationfalse/none字符串到严重级别的映射由parseDiagLevel实现configOptions.tsfalse/none映射为禁用true/error映射为错误warning、information对应警告与提示。在 server.ts 中每一条键值对都会先经getDiagnosticRuleName与getSeverityOverrides双重校验规则名必须在支持列表中、严重级别必须是合法枚举值非法条目被静默丢弃。python.analysis.include / exclude / ignorearray of paths三个路径列表语义各不相同include应被包含在分析范围内的目录或文件路径exclude不应被包含的目录或文件路径ignore虽被包含但应抑制诊断输出错误和警告不报告的目录或文件路径。三者的文档均注明“可在配置文件中覆盖This can be overridden in the configuration file”。在 server.ts 中它们分别映射为includeFileSpecs、excludeFileSpecs、ignoreFileSpecs最终在 analyzerServiceExecutor.ts 写入configSettings。python.analysis.extraPathsarray of paths当配置文件中没有定义 execution environment 时这些路径会被追加到默认执行环境的额外搜索路径extra paths中用于导入解析。每项可含 glob 模式会按确定顺序展开为匹配的目录展开细节就地展开、按码点排序、重复去重、仅对file协议路径生效等规则见 import-resolution.md 的 “Extra Path Glob Expansion” 一节。源码中这些条目经resolvePathStringWithEnvVariables解析后存入extraPathFileSpecsserver.ts。python.analysis.autoSearchPathsboolean当配置文件中未定义 execution environment 时决定 Pyright 是否自动添加如src之类的常见搜索路径。其默认值与是否配置了python.analysis段相关从 server.ts 看若客户端完全没有提供python.analysis配置段autoSearchPaths默认为true否则显式取值未设置即为false。实际添加默认路径的逻辑在ensureDefaultExtraPathsconfigOptions.ts。python.analysis.autoImportCompletionsboolean决定 Pyright 是否提供自动导入补全在补全列表中提示从其他模块导入的符号。默认值为true在 server.ts 中显式初始化可通过python.analysis.autoImportCompletions设置覆盖server.ts。python.analysis.useLibraryCodeForTypesboolean决定在缺少类型存根文件时Pyright 是否读取、解析并分析库代码本身来提取类型信息此时提取到的类型信息通常是不完整的官方建议尽可能使用类型存根。默认值为true。python.analysis.stubPathpath指向包含自定义类型存根文件的目录。在 server.ts 中解析后存入stubPath并在 analyzerServiceExecutor.ts 中写入configSettings.stubPath供导入解析器在查找第三方库存根时优先检索。python.analysis.typeshedPathsarray of pathstypeshed 模块的查找路径。Pyright 当前只认可数组中的第一个路径——这一行为既写在文档里也直接体现在源码中server.ts 只取typeshedPaths[0]且 analyzerServiceExecutor.ts 中的注释明确说明“官方 VS Code Python 扩展支持多个 typeshed 路径Pyright 只使用第一个其余忽略”。python.analysis.logLevelError | Warning | Information | Trace输出面板Output panel的日志级别默认值为Information。大小写不敏感的级别转换在convertLogLevel中完成console.tserror/warning/information/trace分别映射到四个LogLevel未知值回退为Information。有一个值得注意的实现细节当日志级别为Trace时getEffectiveCommandLineOptions会同时打开verboseOutputanalyzerServiceExecutor.ts从而输出分析服务的详细日志——这也是调试导入解析问题时推荐的配置。python.* 前缀设置解释器环境python.pythonPathpath指向 Python 解释器的路径。文档注明该设置正被 VS Code Python 扩展弃用改为存放在 Python 扩展的内部配置存储中Pyright 两种机制都支持但两者同时存在时优先使用新机制。源码中有两个细节特殊值python会被忽略analyzerServiceExecutor.ts 的注释说明 VS Code Python 扩展将python解释为“使用本地解释器”而非路径Pyright 通过isPythonBinarypythonPathUtils.ts识别并跳过这种值路径值支持环境变量替换由resolvePathWithEnvVariables处理server.ts。python.venvPathpath指向“包含多个虚拟环境子目录”的父目录注意与python.pythonPath指向具体解释器不同。文档建议在大多数场景下优先使用python.pythonPath机制环境配置的完整说明参见 import-resolution.md 的 “Configuring Your Python Environment” 一节。设置速查表设置项类型默认值说明状态pyright.disableLanguageServicesbooleanfalse禁用全部语言服务hover、补全、跳转等保留类型检查有效pyright.disableOrganizeImportsbooleanfalse禁用 Organize Imports 命令有效pyright.disableTaggedHintsbooleanfalse禁用带 tag 的提示类诊断灰色不可达代码、删除线弃用项有效pyright.openFilesOnlyboolean—仅分析打开的文件已弃用改用python.analysis.diagnosticModepyright.useLibraryCodeForTypesboolean—无存根时解析库代码已弃用改用python.analysis.useLibraryCodeForTypespython.analysis.autoImportCompletionsbooleantrue是否提供自动导入补全有效python.analysis.autoSearchPathsbooleantrue未配置 analysis 段时无执行环境时自动添加src等常见搜索路径有效python.analysis.diagnosticModeopenFilesOnly | workspace—分析范围仅打开文件 / 整个工作区有效python.analysis.diagnosticSeverityOverridesmap—按规则名覆盖严重级别error/warning/information/true/false/none有效python.analysis.excludearray of paths—排除的目录/文件可被配置文件覆盖有效python.analysis.extraPathsarray of paths—追加到额外搜索路径支持 glob有效python.analysis.ignorearray of paths—抑制诊断输出的目录/文件可被配置文件覆盖有效python.analysis.includearray of paths—包含的目录/文件可被配置文件覆盖有效python.analysis.logLevelError | Warning | Information | TraceInformation输出面板日志级别Trace 同时开启 verbose 输出有效python.analysis.stubPathpath—自定义类型存根目录有效python.analysis.typeCheckingModeoff | basic | standard | strictstandard默认类型检查级别可被配置文件覆盖旧名pyright.typeCheckingMode仍被认可有效python.analysis.typeshedPathsarray of paths—typeshed 查找路径仅第一个生效有效python.analysis.useLibraryCodeForTypesbooleantrue无存根时解析库代码提取类型有效python.pythonPathpath—Python 解释器路径与 Python 扩展新机制并存时优先新机制有效python.venvPathpath—包含虚拟环境子目录的目录优先推荐使用python.pythonPath有效表中默认值可溯源至 server.ts 中getSettings构造的初始ServerSettings对象openFilesOnly: true、useLibraryCodeForTypes: true、typeCheckingMode: standard、logLevel: LogLevel.Info、autoImportCompletions: true等。设置如何生效从设置值到分析服务理解这些设置的实际作用路径有助于排查“改了设置不生效”的问题。完整调用链为客户端发送配置变更通知onDidChangeConfiguration触发updateSettingsForAllWorkspaceslanguageServerBase.ts每个工作区重新执行getSettings拉取最新设置updateSettingsForWorkspace先把日志级别、disableLanguageServices、disableTaggedHints、disableOrganizeImports写入 workspace 对象languageServerBase.tsupdateOptionsAndRestartService调用AnalyzerServiceExecutor.runWithOptions由getEffectiveCommandLineOptions把ServerSettings转换为CommandLineOptions检查范围、存根路径、额外搜索路径、诊断覆盖、严重级别覆盖等见 analyzerServiceExecutor.ts再通过workspace.service.setOptions使分析服务带着新选项全量重新分析。其中两个值得记住的行为设置变更会触发全量重新分析runWithOptions中的注释明确写着 “Setting options causes the analyzer service to re-analyze everything”因此切换typeCheckingMode或diagnosticMode后诊断结果会整体刷新openFilesOnly 模式下诊断推送行为不同当工作区处于 open-files-only 模式且客户端支持 pull diagnostics 时Pyright 会发送DiagnosticRefreshRequest请求客户端重新拉取诊断languageServerBase.ts而非推送整个工作区的诊断。与相关文档的衔接配置文件的完整语法pyrightconfig.json、pyproject.toml、execution environment、reportXXX规则全表及默认值configuration.md导入解析顺序、extra path glob 展开规则、Python 环境配置与导入问题调试import-resolution.md命令行使用方式command-line.md需要注意的适用前提本文所有结论基于当前仓库中 Pyright 语言服务器的实现packages/pyright-internal设置名、默认值与校验逻辑均以 server.ts 与 analyzerServiceExecutor.ts 中的实际代码为准标注为“已弃用”的设置项在未来版本中可能被移除新配置应尽量使用python.analysis.*推荐命名。【免费下载链接】pyrightStatic Type Checker for Python项目地址: https://gitcode.com/GitHub_Trending/py/pyright创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考