一、项目简介：Pylance 是什么
Pylance 是微软为 VS Code 打造的、快速且功能丰富的 Python 语言支持服务器。仓库 microsoft/Pylance 主要用于收集反馈与发布文档，Pylance 的代码库本身并不开源；它的核心类型引擎建立在开源的 Pyright 之上，如果你想改进核心类型推断，可以向 Pyright 仓库贡献代码。Pylance 是 VS Code 中 Python 的默认语言支持，并作为 Python 扩展的一个可选依赖被自动附带安装。名字本身是向《巨蟒与圣杯》里第一位回答桥守人问题的骑士兰斯洛特（Lancelot）致敬。
它为 Python 3 提供文档字符串、带类型信息的签名帮助、参数提示、代码补全、自动导入（以及添加/移除 import 的代码操作）、边输入边报出的错误与警告诊断、代码大纲、代码导航、类型检查模式、原生多根工作区支持、Jupyter Notebook 兼容、语义高亮等能力。
除上面提到的能力外，Pylance 还提供：为工作区根目录、资源管理器文件夹与 Python 脚本生成依赖文件（Pylance: Generate Dependency File）、Python 块注释切换（Pylance: Toggle Block Comment）、自动查找并为已装依赖安装类型存根包（Pylance: Install Matching Type Stubs），以及面向事实的 Copilot Chat 技能（类型推断、内联类型注解、查找经审核的第三方存根、存根编写、重构、性能优化等）。它还原生支持多根工作区与 Jupyter Notebook。
之所以"快"，是因为它的核心类型引擎 Pyright 用 TypeScript 编写、运行在独立进程里，借助增量分析与索引，在大型代码库上也能给出近乎实时的补全与诊断。相比更早的 Jedi 语言服务器，Pylance 在类型推断准确度、补全速度与语义高亮上都有明显提升，因此成为 VS Code Python 的默认选择。
二、环境准备与前置依赖
Pylance 是 VS Code 扩展形态的语言服务器，部署前请确认：
- 已安装 Visual Studio Code；
- 系统里已装好受支持版本的 Python，并在 VS Code 中选定了解释器；
- 网络可访问 VS Code Marketplace（离线场景见后文 VSIX）。
理解部署 Pylance 的关键在于它的运行方式：Pylance 是一个在后台独立进程里运行的语言服务器，通过 LSP 与 VS Code 通信。它启动时会加载你所选解释器的标准库与第三方包、建立索引，随后才能提供补全与诊断。因此第一次打开大项目时，右下角可能短暂显示 "Pylance: indexing…"，属于正常现象。
Pylance 内置了运行所需的 Node 运行时，绝大多数用户无需自己安装 Node。只有在遇到内存问题、或需要指定 Node 版本时，才需要通过 python.analysis.nodeExecutable 手动指定。若把它设为 auto，Pylance 会自动从 nodejs.org 下载一份 Node；自定义 Node 的好处是可以通过 python.analysis.nodeArguments（默认 --max-old-space-size=8192）给语言服务器分配更大的堆内存，避免在超大项目上 OOM。
三、部署方式一：随 Python 扩展自动安装（推荐）
最省事的方式就是先装 Python 扩展，Pylance 会作为可选扩展自动装上：
第 1 步：从市场安装 Python 扩展，Pylance 会作为可选扩展自动安装。
第 2 步：打开一个 Python（.py）文件，Pylance 扩展会自动激活。激活成功后，左下角状态栏会显示语言服务器状态，把鼠标悬停在函数或变量上会出现文档悬浮提示，输入时会有智能补全下拉框。可以在命令面板输入 Pylance: 查看它提供的所有命令，例如重新加载语言服务器、生成依赖文件、安装匹配的类型存根等。
注意：如果你以前手动把语言服务器设成了别的（例如旧的 Jedi），需要在 settings.json 里把 "python.languageServer" 设为 "Default" 或 "Pylance"，或通过设置 UI 选择，否则 Pylance 不会生效。
{
"python.languageServer": "Pylance"
}四、部署方式二：单独安装 / VSIX 离线安装
你也可以直接在扩展面板搜索 "Pylance"（发布者 Microsoft）单独安装。在内网或隔离环境，则到 Pylance 的 Marketplace 页面下载 VSIX，再通过扩展面板的 "Install from VSIX..." 或命令行安装：
code --install-extension ms-python.vscode-pylance-xxx.vsix安装后同样打开一个 .py 文件触发激活。Pylance 会随 Python 扩展一起自动更新；若需要体验预览版，可在扩展详情页切换到 Pre-release 版本，抢先试用新特性，但稳定性不如正式版。当前文档对齐到 Pylance 2026.4.100，新版本通常会带来性能改进、新代码操作与对新版 Python 语法的支持。
五、核心配置与调优
Pylance 提供大量设置，可写在工作区 settings.json 或通过设置 UI 调整。几个最常用的：
python.analysis.languageServerMode：预设三档light（轻量省内存）、default（平衡，默认）、full（最全 IntelliSense）。light会关闭索引、自动导入等以换取低资源占用；full开启自动导入补全、更厚的索引等。python.analysis.typeCheckingMode：类型检查强度，取值off（默认）、basic、standard、strict。在大型代码库里设为off能减少诊断、提升性能。python.analysis.diagnosticMode：openFilesOnly（默认，只对打开的文件做完整诊断）或workspace。大项目建议保持openFilesOnly。python.analysis.extraPaths：添加额外的 import 搜索路径，解决 "unresolved import"。python.analysis.indexing：是否索引第三方库与用户文件以改善自动导入、工作区符号搜索；关闭可省资源但功能变少。python.analysis.nodeExecutable与python.analysis.nodeArguments：遇到内存溢出时指定自定义 Node，参数默认--max-old-space-size=8192。
三档模式对应的默认设置差异较大：light 模式会把 exclude 设为 ["**"]、关闭索引与自动导入、把 useLibraryCodeForTypes 设为 false，接近一个精简编辑器；default 平衡开启大多数实用功能；full 则额外开启自动导入补全、内联返回类型提示、索引所有用户文件（userFileIndexingLimit 为 -1）、自动下载 Node 等。个别设置可以单独覆盖模式默认值，从而在不切换整档的情况下微调。
内联提示（inlay hints）方面，可以用 python.analysis.inlayHints.functionReturnTypes、variableTypes、callArgumentNames、pytestParameters 等设置在代码中显示函数返回类型、变量类型、调用参数名与 pytest fixture 类型，默认大多关闭，full 模式下自动开启。诊断严重程度覆盖示例：
{
"python.analysis.diagnosticSeverityOverrides": {
"reportUnboundVariable": "information",
"reportImplicitStringConcatenation": "warning"
}
}可用严重级别为 error（红色波浪线）、warning（黄色）、information（蓝色）、none（关闭该规则）。若你的项目根目录有 pyrightconfig.json 或 pyproject.toml 中的 [tool.pyright] 配置，它们会覆盖 typeCheckingMode 等设置。
语义高亮方面，VS Code 默认用 TextMate 语法做词法高亮，而 Pylance 作为语言服务器能根据项目上下文提供语义 token，在 TextMate 之上叠加更精确的着色（例如区分函数、类、变量、模块）。下面两张图直观对比了关闭与开启语义高亮的差别：
关闭语义高亮：
开启语义高亮后：
主题可以选择启用语义 token，编辑器会在 TextMate 词法着色之上叠加语义 token 着色。Pylance 提供的语义 token 类型包括 class、enum、parameter、variable、property、function、method、module、intrinsic、magicFunction（双下划线方法）、selfParameter 等；修饰符包括 declaration、readonly、static、abstract、async、typeHint、decorator、builtin、library 等。你可以在 settings.json 的 editor.semanticTokenColorCustomizations 里自定义这些 token 的颜色，例如把装饰器、库函数、类型提示染上特定颜色。
代码操作（灯泡菜单或 Ctrl+.）方面，Pylance 提供移除未使用的 import、添加缺失 import、把 import * 展开为显式导入、提取变量/方法、添加类型注解、实现抽象类等快速修复与重构；启用 GitHub Copilot Chat 后还能获得生成文档字符串、生成函数/类等 AI 辅助代码操作。
六、常见问题与 FAQ（含报错解决）
Q1：Pylance 反复崩溃、停止重启了怎么办？
A：桌面版 VS Code 中 Pylance 会在异常退出后自动重启，但为避免无限崩溃循环，连续崩溃五次后会停止重启（除非两次失败间持续运行满 10 分钟）。此时应打开 Pylance 的 Output 面板（输出通道）查看崩溃详情，对症处理后再 Developer: Reload Window。常见原因是内存不足，可设置 python.analysis.nodeExecutable 指向一个能分配更大内存的 Node，并调大 --max-old-space-size。
Q2：提示 "Import could not be resolved" / unresolved import？
A：先确认选对了解释器（包是否装在当前环境里）；若项目用了 src/ 布局，把目录加进 python.analysis.extraPaths；也可以直接用灯泡菜单里的 "Add ... to python.analysis.extraPaths" 快速修复。
Q3：类型检查报了一堆错，想关掉或降级？
A：把 python.analysis.typeCheckingMode 从 strict/standard 降为 off；也可以用 python.analysis.diagnosticSeverityOverrides 单独把某条规则降为 warning/information/none，例如把 reportUnboundVariable 降为提示。
Q4：Pylance 卡、占内存高怎么优化？
A：改用 languageServerMode 为 light；关闭 python.analysis.indexing；用 python.analysis.exclude 排除不需要分析的目录；把 diagnosticMode 设为 openFilesOnly；减少 python.analysis.userFileIndexingLimit。
Q5：Pylance 不是开源的，能二次开发吗？
A：Pylance 本身闭源，但它的类型引擎 Pyright 是开源的。要改进核心类型检查能力，请向 Pyright 贡献；Pylance 也内置了来自 typeshed 与 microsoft/python-type-stubs 的类型存根。
Q6：怎么切换到用 Pyright 或 Pyrefly 做诊断？
A：通过 python.analysis.diagnosticsSource，可选 Pylance（默认）、Pylance + Pyright（用指定版本 Pyright 替换诊断）或 Pylance + Pyrefly（用 Facebook 的 Pyrefly 做诊断，需要 1.1.1+，可自动下载）。
Q7：为什么补全里出现大量无关的导入建议？
A：这是自动导入在索引第三方包。若想精简，可开启 python.analysis.showOnlyDirectDependenciesInAutoImport，只显示 requirements.txt/pyproject.toml 里声明的直接依赖；或关闭 python.analysis.autoImportCompletions。
Q8：装了某个包却没有类型提示，一堆 "Unknown import"？
A：部分包不自带类型。运行命令面板的 Pylance: Install Matching Type Stubs，它会自动查找并安装对应的类型存根包（如 types-requests、types-pillow）。也可以设 python.analysis.useLibraryCodeForTypes 为 true，让 Pylance 在没有存根时直接解析库源码推断类型。
Q9：可以同时保留旧的 Jedi 语言服务器吗？
A：不建议。Pylance 已是默认且功能更强，旧的 Jedi 已逐步退出。通过 python.languageServer 在 Pylance 与 Jedi 间切换即可，但日常开发应使用 Pylance。
切换语言服务器后建议执行一次 Developer: Reload Window，让新的语言服务器完全接管。旧版 Jedi 在大型项目上的补全速度与类型推断准确度都明显落后，新项目无需再考虑它。
关于类型检查的实践建议：日常业务项目用 basic 或 standard 即可，既能挡住明显错误又不会被规则淹没；开源库或框架级代码再上 strict。配合 # pyright: ignore[规则名] 可以在个别地方豁免，而不必全局放宽。
对于大型 monorepo，合理利用 python.analysis.exclude 排除构建产物、node_modules、虚拟环境目录能显著降低索引负担；默认情况下 Pylance 已自动排除这些目录（可由 useDefaultExcludes 控制）。若项目里有大量生成代码，也应把对应目录加入 exclude。
Q10：多根工作区 / monorepo 里不同子项目要用不同解释器怎么办？
A：开启 python.analysis.usePerProjectEnvironments，并通过 python-envs.pythonProjects 声明各子项目；必要时用 extraPaths 或开启 addExtraPathsForPythonProjects 让跨项目 import 正确解析。
Q11：想完全关掉 Pylance 的所有警告/红线？
A：把 python.analysis.typeCheckingMode 设为 off，并把 python.analysis.diagnosticMode 设为 openFilesOnly；若只想屏蔽某目录，用 python.analysis.ignore。临时忽略单行可在该行末尾加 # pyright: ignore[规则名]。
七、总结与相关资源
Pylance 是 VS Code Python 开发体验的"大脑"：装好 Python 扩展即自动获得，把 python.languageServer 确认设为 Pylance，再按需用 languageServerMode、typeCheckingMode、extraPaths 等设置调优，就能获得快速补全、精确诊断与语义高亮。遇到崩溃先看 Output 通道，遇到 import 报错先核对解释器与 extraPaths。部署验收很简单：打开一个项目文件，确认悬停有文档、输入有补全、故意写错一行能看到红色波浪线，即说明 Pylance 已正常工作。
更多资料：更新日志 CHANGELOG、仓库内的 故障排查 TROUBLESHOOTING、Pyright 与 Pyright 配置文档。提 Bug 请到 pylance-release Issues。日常使用中，记住三个高频排错动作：选对解释器、把项目根加进 extraPaths、内存不够就调大 Node 堆，就能解决绝大多数 Pylance 问题。