Pylance未正确启用或配置会导致Python开发中补全不准、类型提示缺失、跳转失败等问题，需依次确认启用Pylance语言服务器、配置pyrightconfig.json、指定venv解释器路径、禁用冲突扩展、重置Pylance缓存。
如果您在使用VSCode进行Python开发时发现代码补全不准确、类型提示缺失或跳转定义失败，很可能是Pylance插件未正确启用或配置。以下是针对Pylance插件的核心功能启用与问题排查步骤：
本文运行环境：MacBook Pro，macOS Sequoia。
一、确认Pylance已安装并设为默认Python语言服务器
Pylance是微软官方推出的专为Python优化的语言服务器，需明确启用才能替代默认的Jedi引擎。该设置直接影响类型推断、符号导航和语义高亮等核心体验。
1、打开VSCode命令面板（快捷键 Cmd+Shift+P）。
立即学习“Python免费学习笔记（深入）”；
2、输入并选择 Python: Select Language Server。
3、在弹出选项中点击 Pylance。
4、重启当前Python文件的编辑器窗口以激活变更。
二、配置pyrightconfig.json启用高级类型检查
Pylance底层依赖Pyright，通过项目根目录下的pyrightconfig.json可启用严格模式、自定义类型根路径及忽略路径，显著提升静态分析精度。
1、在工作区根目录新建文件，命名为 pyrightconfig.json。
2、写入以下基础配置内容：
{"typeCheckingMode": "basic", "include": ["src/**"], "exclude": ["**/node_modules/**", "**/__pycache__/**"]}。
3、保存文件后，Pylance将在下次文件保存时自动加载该配置。
三、解决Pylance无法识别venv中包的问题
当虚拟环境中安装的第三方库在VSCode中显示为未解析导入时，通常因Pylance未正确识别venv路径。需手动指定解释器路径以同步包索引。
1、按下 Cmd+Shift+P 打开命令面板。
2、执行 Python: Select Interpreter。
3、从列表中选择指向当前项目venv内python可执行文件的路径，例如 ./venv/bin/python。
4、等待右下角状态栏出现 Pylance is analyzing... 提示，表示索引重建开始。
四、禁用冲突扩展避免语法高亮异常
部分旧版Python扩展（如原始Python扩展的旧版本）或第三方语法增强插件会与Pylance的语义高亮机制产生竞争，导致变量名颜色错乱或注释样式失效。
1、点击左侧扩展图标，进入扩展管理界面。
2、在搜索框中输入 python，定位到非Microsoft发布的Python相关扩展。
3、对名称含 Python for VS Code 或 MagicPython 的扩展执行停用操作。
4、关闭并重新打开当前Python文件，观察高亮是否恢复正常。
五、重置Pylance缓存强制重建类型数据库
Pylance会在本地生成缓存索引以加速后续分析，但缓存损坏会导致类型提示丢失或跳转失败。清除缓存可触发全新索引构建过程。
1、打开VSCode命令面板（Cmd+Shift+P）。
2、输入并选择 Developer: Toggle Developer Tools。
3、切换至Console标签页，粘贴并执行以下命令：localStorage.removeItem('pylance-cache');。
4、关闭开发者工具，执行 Developer: Reload Window 重启编辑器窗口。
