VS Code Python扩展装好后Pylance不工作怎么办

在安装官方的 VS Code Python 扩展后，编辑器本应自动启用 Pylance 作为默认的语言服务器（Language Server），以提供变量类型推断、自动补全、函数签名预览与跨文件跳转功能。然而不少开发者会遇到代码没有任何智能提示、按住 Ctrl 或 Command 键无法跳转函数、甚至右下角状态栏不断转圈却毫无反应的情况。核心解决路径通常集中在四步：确认 Python 解释器已显式绑定、核实语言服务器设置未被回退、查看 Pylance 输出日志锁定报错源、以及排除扩展版本与缓存冲突。

一、Pylance 在 VS Code 中的协作关系

很多初学者误以为 Python 扩展自身负责所有语法分析，实际上 VS Code 的 Python 支持是由多个组件分层协作完成的。官方的 Python 扩展（ms-python.python）主要充当宿主与环境调度器，负责检测系统中的虚拟环境、Conda 环境并与调试器对接；而真正的静态分析、类型推断和代码智能补全则委托给 Pylance 扩展（ms-python.vscode-pylance）。Pylance 底层基于微软的 Pyright 类型检查引擎，它必须依托一个明确有效的 Python 运行环境来确定模块搜索路径（sys.path）。

图 1：VS Code 编辑器、Pylance 语言服务器与本地 Python 运行环境的依赖拓扑

只要上述三者之间的任意一环出现断裂——例如未选择解释器导致 Pylance 找不到模块定义，或者设置中禁用了 Pylance，语言功能就会整体失效。

二、标准排查步骤：由表及里的四大环节

当发现代码没有语法高亮或自动补全时，应当遵循一套清晰、递进的顺序排查，而不是盲目重装软件。

图 2：排查 Pylance 不工作问题的执行顺序

步骤 1：确认已正确选择 Python 解释器

Pylance 无法工作的首要高发原因，是在当前工作区中没有为 Python 文件绑定具体的解释器。打开 .py 文件后，请观察 VS Code 界面底部状态栏（通常在右侧或左下角）：

• 若状态栏显示“选择解释器”（Select Interpreter），说明当前工作区未检测到环境。
• 按快捷键 Ctrl+Shift+P（macOS 为 Cmd+Shift+P）调出命令面板。
• 输入并选择 Python: Select Interpreter。
• 在列表中选择当前项目实际使用的 Python 路径（如虚拟环境 .venv/bin/python 或 Conda 环境）。

选定解释器后，等待 3 到 5 秒，通常状态栏会显示“正在启动语言服务器”，随后代码即恢复高亮与补全。

步骤 2：显式锁定 Language Server 为 Pylance

在某些历史配置或多扩展共存（如同时安装了 Jedi、Kite 或旧版 Microsoft 语言服务器）的情况下，VS Code 的语言服务器可能被回退为其他引擎甚至被设为 None。

按 Ctrl+,（macOS Cmd+,）打开设置，在搜索栏中输入 python.languageServer，确保该项的值明确为 Pylance 或 Default。

若习惯使用 settings.json 统一管理，可直接在 .vscode/settings.json 中核对以下键值：

{
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "basic"
}

如果此项被误配为 Jedi 或 None，Pylance 将被完全旁路，无法加载。

步骤 3：查看 Output 输出面板的真实报错信息

若前两项配置均正常但依然没有补全，此时需要查看 Pylance 进程的运行状态。通过快捷键 Ctrl+Shift+U（macOS Cmd+Shift+U）打开“输出”（Output）面板，在右侧下拉菜单中选择 Python Language Server 或 Pylance。

图 3：VS Code 输出日志面板中 Pylance 启动失败的典型表现

在正常情况下，日志中会依次打印 Pylance 版本、搜索到的 Python 环境路径以及分析完成的文件数。若日志停留在 Connection to server got closed 或出现大量异常堆栈，表明其核心语言服务进程崩溃。

步骤 4：处理版本不匹配与缓存冲突

当输出日志报告服务意外中断时，大多是因为 VS Code 本身版本过旧，或者安装了 Pylance 的预发布版（Pre-Release Version），导致其与 Python 扩展内部的接口不匹配：

1. 在 VS Code 扩展面板（Ctrl+Shift+X）中搜索 Pylance。
2. 如果当前安装的是预发布版，点击“切换到发行版”（Switch to Release Version）。
3. 如果最新发行版依然崩溃，可点击齿轮图标，选择“安装另一个版本...”（Install Another Version...），回退 1 到 2 个次版本号（例如从上个月的最新版本回退至上一个稳定版本）。

三、常见故障场景与针对性解决方案

除了语言服务器未启动外，读者还会遇到几种特定形态的“假死”或“不生效”，其排查重心各不相同。

{
  "python.analysis.extraPaths": [
    "${workspaceFolder}/src"
  ]
}

{
  "python.analysis.ignore": [
    "**/node_modules/**",
    "**/.git/**",
    "**/build/**",
    "**/dist/**",
    "**/data/**"
  ]
}

四、排查逻辑全景总结

遇到 Pylance 不工作时，无需恐慌或重装整套开发环境。根据以下判定树，绝大多数问题都可以在两分钟内完成定位：

图 4：Pylance 故障排查逻辑判定图

只要根据这套逻辑逐一确认解释器关联、语言服务器配置、输出日志以及路径索引范围，便能快速恢复 VS Code 流畅的代码提示与语义分析体验。