Pylance 未正确启用或配置会导致 VSCode 中 Python 智能提示不准、类型推断缺失、跳转定义失败；需确认安装并设为默认语言服务器、检查版本兼容性、配置 pyrightconfig.json、重置缓存、禁用冲突扩展。
如果您在使用 VSCode 编写 Python 代码时发现智能提示不准确、类型推断缺失或跳转定义失败，则可能是 Pylance 扩展未正确启用或配置。以下是针对该语言服务器的常见配置与调试操作：
本文运行环境：MacBook Pro，macOS Sequoia。
一、确认 Pylance 已安装并设为默认语言服务器
Pylance 是 微软 为 Python 提供的高性能语言支持扩展，需显式启用才能替代默认的 Jedi 引擎。VSCode 会优先使用 workspace 或 user 级别的设置来决定激活的语言服务器。
1、打开 VSCode 的设置界面（快捷键 Cmd + ,）。
立即学习“Python 免费学习笔记（深入）”；
2、在搜索栏中输入 python.defaultInterpreterPath，确保已指定有效的 Python 解释器路径。
3、继续搜索 python.languageServer，将其值设为 Pylance。
4、重启 VSCode 窗口使设置生效。
二、检查 Pylance 扩展状态与版本兼容性
Pylance 依赖 VSCode 的 Language Server Protocol 实现功能，若扩展版本与当前 VSCode 版本不匹配，可能导致语法高亮异常或诊断信息丢失。
1、点击左侧活动栏的扩展图标（方块拼图形状）。
2、在搜索框中输入 Pylance，确认其状态为“已启用”且版本号不低于 2024.10.1。
3、若显示“更新可用”，点击右侧更新按钮执行升级。
4、右键点击 Pylance 条目，选择“禁用”，再重新启用以刷新服务实例。
三、配置 pyrightconfig.json 启用高级类型检查
Pylance 底层基于 Pyright 构建，通过项目根目录下的 pyrightconfig.json 文件可开启严格类型验证、未使用符号警告等能力。
1、在当前工作区根文件夹中新建文件，命名为 pyrightconfig.json。
2、填入以下基础配置内容：
{
“include”: [“**/*.py”],
“exclude”: [“**/node_modules”, “**/__pycache__”],
“typeCheckingMode”: “basic”
}
3、将 typeCheckingMode 的值改为 strict 以启用完整类型校验。
4、保存文件后，等待右下角状态栏出现“Pylance: Ready”提示。
四、重置 Pylance 缓存强制重建索引
当项目结构发生大规模变更（如新增包、修改 __init__.py 或切换 虚拟环境）时，Pylance 的本地缓存可能失效，导致跳转错误或无法识别模块。
1、按下 Cmd + Shift + P 打开命令面板。
2、输入并选择 Python: Restart Language Server。
3、若问题持续，执行 Developer: Toggle Developer Tools，在 Console 标签页中粘贴并运行：
await require(‘vscode‘).workspace.getConfiguration(‘python’).update(‘languageServer’, ‘Pylance’, true)
4、关闭开发者 工具，再次触发重启命令。
五、禁用冲突扩展避免服务抢占
部分第三方 Python 扩展（如 Python Docstring Generator、Auto Import）可能注册同名语言功能提供者，干扰 Pylance 的语义分析流程。
1、进入扩展视图，筛选已启用的 Python 相关扩展。
2、临时禁用所有非微软官方发布的 Python 工具类扩展。
3、逐一启用并观察 Pylance 是否恢复正常诊断行为。
4、记录引发冲突的扩展名称，并在其设置中关闭 python.analysis.extraPaths 或类似注入机制。
