PAYATHON 2026

VSCode 中 Pylance 与 Pyright 的诊断重复、禁用后检查失效怎么办?

数据小陈

结论

Pylance 内置了 Pyright 的类型检查功能,正常情况下不依赖独立的 Pyright 扩展,也不需要运行 sudo apt install pyright。建议先只保留 Pylance 负责编辑器中的类型诊断,再检查类型检查配置。Pyright 官方安装说明

两条提示都显示为 Pylance,还不能说明两个扩展发生了冲突。先比较它们是完全相同的诊断,还是同一段代码触发了不同的检查规则。仅凭现有信息还无法确定具体原因。

为什么禁用 Pyright 后看不到类型错误?

先检查 python.analysis.typeCheckingMode。Pylance 的默认值是 off。在这个模式下,Pylance 会关闭大多数类型检查诊断,但仍会报告无法解析的导入、未定义的变量等问题。所以,即使 int(None) 不再出现类型提示,Pylance 仍可能在进行静态分析。Pylance 配置说明

在系统中安装 Pyright 和启用 VSCode 扩展是两回事。安装命令不会修复 Pylance 的设置,也不会自动清除编辑器中的重复诊断。

先恢复 Pylance 的独立类型检查

  1. 在扩展面板中确认 Microsoft 的 Python 扩展和 Pylance 都已启用,并禁用独立的 Pyright 扩展。如果使用 WSL、SSH 或 Dev Container,也要检查当前远程环境中的扩展状态。
  2. 打开工作区的 .vscode/settings.json,将下面的设置合并到现有配置中:
{
  "python.analysis.typeCheckingMode": "basic"
}
  1. 检查项目是否已有 pyrightconfig.json,或 pyproject.toml 中的 [tool.pyright] 配置。这些配置可能覆盖 VSCode 中的类型检查设置。如果项目已经统一管理检查模式,应修改现有配置,例如在 pyrightconfig.json 中设置:
{
  "typeCheckingMode": "basic"
}

不要用这个最小示例覆盖整个配置文件。如果 pyrightconfig.json 和 pyproject.toml 同时存在,前者优先。Pyright 配置说明

  1. 在命令面板中执行 Developer: Reload Window,重新打开一个 .py 文件,检查类型诊断是否恢复。

如果当前 Pylance 版本提供 python.analysis.diagnosticsSource 设置,也检查它是否被改成了其他诊断提供者。要使用 Pylance 自带的检查器,可以选择 Pylance;旧版本没有该设置时可以跳过。Pylance 诊断来源设置

判断两条提示是否真的重复

在单独的 Python 文件中保留原来的示例:

int(None)

打开 Problems 面板,逐项比较两条提示的完整消息、规则代码和对应位置。

同一个调用可能同时触发多个检查规则。只要规则或消息不同,就应先按不同诊断处理。两条提示都来自 Pylance,也不能据此认定语言服务器启动了两次。

如果两条诊断的消息、规则代码和位置都相同,再继续排查重复发布的问题。int(None) 本身是无效调用,运行时会抛出 TypeError。排查时应消除多余提示,同时保留有效的类型检查。

完全相同的诊断仍出现时怎么排查?

先在 Output 面板选择 Pylance。如果没有该通道,也查看 Python 通道,确认扩展是否正常启动,以及是否出现配置或启动错误。

然后用 VSCode 的临时配置文件打开一个空文件夹,文件夹中只保留上述示例文件。仅启用 Microsoft Python 和 Pylance,并将 typeCheckingMode 设置为 basic:

  • 如果新环境中不再重复,逐步恢复原工作区设置和其他扩展,定位触发条件。
  • 如果新环境中仍然重复,记录 VSCode、Python 扩展和 Pylance 的版本,以及两条完整诊断和相关日志,再向 Pylance 提交可复现的问题。

如果工作区还配置了调用 Pyright 的任务及 problemMatcher,也要检查它是否把命令行检查结果写入了 Problems 面板。存在这类额外集成时,才需要将命令行结果纳入此次排查。

不要通过关闭全部类型检查来消除重复提示,这也会隐藏本来应该报告的问题。

备注:内容仅供参考。