当你在 VSCode 中享受行云流水的代码补全时，可能从未想过，那个默默工作的“大脑”——语言服务器，其配置的微妙差异，正深刻影响着你的编码效率和最终代码质量。有时，减少一些检查，反而能让你更专注于真正重要的问题。

前言：你每天都在用，却可能从未真正了解的“幕后大脑”

对于使用 VSCode 进行 Python 开发的程序员来说，智能的代码补全、红色的错误波浪线、一键导入模块等功能已如呼吸般自然。这一切体验的幕后功臣，便是 Python 语言服务器。

然而，当提及 Pylance、Pyright、BasedPyright、Jedi 这些名词时，许多开发者往往感到模糊。它们是什么关系？我该用哪个？那些复杂的检查等级设置到底有什么用？本文旨在揭开这层神秘面纱，带你从原理到实践，彻底搞懂 Python 语言服务器，并学会如何通过精妙配置，让它真正成为提升你代码质量的利器，而非束缚。

核心概念：语言服务器与 LSP 协议

在深入具体工具前，我们必须理解两个基石概念。

语言服务器是什么？

想象一下，你的代码编辑器（如 VSCode）是一个“前台接待”，它负责显示界面、处理你的键盘鼠标操作。而 语言服务器 则是一个后台的“专家顾问”，它精通特定编程语言（如 Python）的所有知识。

当你在编辑器中输入代码时，“前台”会将你的代码文本和光标位置等信息，实时发送给这个“专家”。专家运用其内置的语法分析器、类型推断引擎等进行深度分析，然后将分析结果（如：这里可以补全什么变量、那里有个类型错误、这个函数在哪里定义）返回给“前台”进行展示。

┌─────────────────┐       ① 用户输入代码        ┌─────────────────┐
│                 │ --------------------------> │                 │
│    编辑器       │       ② 发送文档内容         │   语言服务器    │
│   (VSCode)     │ <-------------------------- │  (Pylance等)   │
│                 │       ③ 返回诊断、补全等     │                 │
└─────────────────┘                             └─────────────────┘

这种前后端分离的架构，正是语言服务器协议（LSP）的核心思想。

LSP：统一的“沟通语言”

在 LSP 出现之前，每个编辑器都需要为每种语言编写特定的插件来获得智能支持，工作量呈指数级增长（编辑器数 × 语言数）。LSP 定义了一套标准的 JSON-RPC 通信协议，规定了编辑器（客户端）和语言服务器之间如何沟通。

关键好处：

• 对编辑器开发者：只需实现一次 LSP 客户端，即可支持所有遵循该协议的语言服务器。
• 对语言服务器开发者：只需实现一次 LSP 服务器，即可在所有支持 LSP 的编辑器中运行。
• 对开发者（你）：在 VSCode、Vim、Neovim、Sublime Text 等不同编辑器中，能获得近乎一致的语言智能体验。

主流 Python 语言服务器一览

了解了原理，我们来看看当前 Python 生态中几个主要的“专家顾问”：

1. Pylance

   • 出身：微软官方出品，与 VSCode 深度集成。
   • 核心：基于强大的开源类型检查器 Pyright 构建，并在此基础上增加了大量针对 VSCode 的优化、增强功能（如更智能的自动导入、代码导航）和专有的性能改进。
   • 特点：功能全面、性能卓越、与 VSCode 体验最无缝。它是 VSCode Python 扩展的默认推荐。

2. Pyright

   • 出身：微软开源的、用 TypeScript 编写的 Python 类型检查器和语言服务器。
   • 核心：专注于类型检查和代码分析，速度极快。
   • 特点：可以独立于编辑器使用（例如在 CI/CD 流水线中做静态检查），是 Pylance 的“心脏”。很多配置项两者通用。

3. BasedPyright

   • 出身：社区维护的 Pyright 分支，由 DetachHead 开发。
   • 核心：基于 Pyright，增加了更严格的默认设置、额外的诊断规则，并将一些 Pylance 专有特性开源化。
   • 特点：可通过 pip 安装，使用更便捷；提供更激进的类型检查；适合追求极致类型安全的项目。

4. Jedi

   • 出身：历史悠久的、用 Python 自身编写的自动补全和静态分析库。
   • 核心：专注于代码补全和代码导航（如跳转到定义、查找引用）。
   • 特点：纯 Python 实现，易于理解和扩展。在某些动态特性的补全上表现良好，但在大型项目中的性能和分析深度上，通常不如基于 Pyright 的方案。

5. Python Language Server (PLS)

   • 出身：较早期的开源项目，同样基于 Jedi 和 Rope（另一个重构库）。
   • 特点：功能相对基础，已逐渐被 Pylance 和 Pyright 取代，目前处于维护状态。

简单总结：对于绝大多数 VSCode 用户，Pylance 是开箱即用的最佳选择。如果你需要在编辑器外进行类型检查，或想使用纯开源方案，Pyright 是核心引擎。BasedPyright 则为追求更严格类型检查和开源 Pylance 特性的用户提供了强大替代。Jedi 则是一个可靠的备选。

实战演练：配置你的智能助手

理论之后，让我们动手配置。以下操作均以 VSCode 为例。

场景一：选择与切换语言服务器

VSCode 的 Python 扩展允许你轻松选择使用哪个语言服务器。

1. 打开 VSCode 设置（快捷键 Ctrl+,）。

2. 搜索 python.languageServer。

3. 在下拉菜单中，你会看到几个选项：

   • Pylance (推荐)
   • Pyright
   • Jedi
   • None (禁用所有语言服务器智能功能)

   注意：BasedPyright 需要安装对应的 VSCode 扩展，并在设置中指定 python.languageServer 为 "basedpyright"。

配置文件的直接方式：你也可以在项目根目录的 .vscode/settings.json 文件中直接指定，便于团队统一配置：

{
    "python.languageServer": "Pylance"
}

切换后，VSCode 右下角会显示当前使用的语言服务器名称。你可以尝试在不同服务器下编码，感受补全速度、提示准确度等方面的差异。

场景二：调整检查等级——理解“类型检查模式”

这是本文的核心，也是标题中“关掉某些检查”的关键。以 Pylance/Pyright/BasedPyright 为例，它们提供了一个名为 python.analysis.typeCheckingMode 的关键配置，控制着类型检查的严格程度。

它有三个主要级别：

1. off：关闭所有类型检查相关的诊断。此时，语言服务器主要提供代码补全、导航等基础功能，不会报告类型错误。适合快速原型开发或处理大量无类型注解的旧代码。
2. basic：基础检查模式。这是默认值。它会报告最明显、最可能导致运行时错误的类型问题，例如向一个期望 int 的参数传递 str。但对于更复杂的类型推断和未使用类型注解的情况则比较宽容。
3. strict：严格检查模式。启用所有可用的类型检查规则。它会要求代码具有完整的类型注解，并对类型不一致、未使用的类型忽略注解 (# type: ignore)、可能的 None 值未处理等情况发出警告。适合追求高代码质量、长期维护的新项目。

如何配置？
在 .vscode/settings.json 中：

{
    "python.analysis.typeCheckingMode": "basic" // 可选 "off", "basic", "strict"
}

最佳实践与常见陷阱

为什么“关掉检查”有时更好？

这听起来反直觉，但有其道理：

1. 降低噪音，聚焦核心：在 strict 模式下，一个缺乏类型注解的旧项目可能会产生成百上千的警告。开发者容易陷入“警告疲劳”，反而忽略了真正重要的逻辑错误。暂时切换到 off 或 basic，清理完主要问题后再逐步提升严格度，是更务实的策略。
2. 尊重项目的“现实”：并非所有项目都需要或适合严格的类型检查。对于脚本、快速实验或依赖大量动态特性的库，过严的检查会阻碍开发节奏。工具应服务于人，而非束缚人。
3. 性能考量：strict 模式下，语言服务器需要进行更深层次的分析，在超大型项目中可能会轻微影响响应速度。在资源受限的环境下，basic 是一个很好的平衡点。

配置最佳实践

1. 项目级配置优先：将设置放在 .vscode/settings.json 中并纳入版本控制，确保团队所有人使用相同的语言服务器和检查等级。
2. 渐进式严格化：对于现有项目，可以从 off 或 basic 开始，配合 mypy 等工具逐步添加类型注解，再过渡到 strict。
3. 善用覆盖规则：即使在高严格度下，也可以对特定文件、目录或行禁用检查。例如，在 VSCode 用户设置中为所有测试文件放宽要求：

   {
       "python.analysis.diagnosticSeverityOverrides": {
           "reportMissingTypeStubs": "none",
           "reportUnknownMemberType": "none" // 常见于第三方库未提供类型存根时
       }
   }
   

4. 区分编辑器与 CI：可以在编辑器中使用 basic 模式以获得流畅体验，但在持续集成（CI）流水线中，使用 pyright --verifytypes 或 mypy --strict 命令行工具执行更严格的检查，作为代码合并的门禁。

常见陷阱

• 混淆 Pylance、Pyright 与 BasedPyright 配置：虽然大部分配置项通用，但一些以 python.analysis. 开头的高级配置是 Pylance 专有的。查阅文档时需注意。
• 忽略类型存根（Stubs）：当使用没有内置类型信息的第三方库时，Pylance/Pyright/BasedPyright 会提示找不到类型。安装对应的类型存根包（如 pip install types-requests）通常能解决问题。
• 过度依赖 # type: ignore：这虽然是有用的“逃生舱”，但滥用会掩盖真实问题。最好注明忽略的具体错误代码，如 # type: ignore[assignment]。

总结

Python 语言服务器，尤其是以 Pylance/Pyright/BasedPyright 为代表的现代实现，通过 LSP 协议将强大的静态分析能力带给了每一位开发者。理解其工作原理，并明智地配置检查等级，是提升开发体验的关键。

要点回顾：

1. 语言服务器是编辑器的“后台大脑”，通过 LSP 协议实现跨编辑器的智能功能。
2. Pylance 是 VSCode 的默认且推荐的选择，其核心是开源的 Pyright。
3. typeCheckingMode 是控制严格度的核心开关：off（只补全）、basic（查大错）、strict（全面检查）。
4. 没有“最好”的配置，只有“最合适”的配置。根据项目阶段、团队习惯和性能需求，在智能提示与开发流畅度之间找到平衡点。

延伸阅读：

• Pylance 官方文档
• Pyright 配置指南
• BasedPyright 官方文档
• LSP 官方规范