跳转失效最常见原因是python.languageServer被设为"None"，应优先检查并修改.vscode/settings.json中该配置为"Pylance"或"Default"，再重启语言服务器。
python.languageServer 被设为 "None" 是最常见原因
跳转失效时，第一反应不该是重装插件或重启 VSCode，而是立刻检查 .vscode/settings.json。很多工程里藏着一行："python.languageServer": "None"——这等于手动关掉了整个语言服务。Pylance、Jedi 都不会启动，自然没有定义索引、补全、引用查找。这个设置可能来自误操作、旧版插件迁移残留，或某些“优化性能”的教程误导。
修复只需两步：
- 打开项目根目录下的
.vscode/settings.json，删掉或注释掉"python.languageServer": "None" - 改为
"python.languageServer": "Pylance"（推荐）或"python.languageServer": "Default"
改完保存，再执行命令 Python: Restart Language Server，等待右下角状态栏出现 “Pylance initializing…” 即可。
状态栏显示 Plain Text 或 Python 未激活
VSCode 不会自动给所有 .py 文件启用语义分析。如果右下角状态栏显示 Plain Text、Unsupported 或空白，说明当前文件没被识别为 Python 上下文。
立即学习“Python免费学习笔记（深入）”；
常见诱因：
- 文件未保存（临时
Untitled-1标签页默认不触发语言服务器） - 后缀名异常（如
script.logic.py或main.PY大写） - 工作区未以文件夹形式打开（只打开了单个文件，VSCode 缺少项目根路径，无法解析
from . import xxx）
解决方法：点击状态栏语言标识，手动选择 Python；确保用 File → Open Folder 打开整个项目；检查 settings.json 是否有误配的 files.associations 覆盖了 .py 关联。
Python 解释器路径或环境配置错误
即使 Pylance 启动了，如果 python.defaultInterpreter 指向一个无效路径、空环境，或 Conda 环境里缺 pip / setuptools，语言服务器会静默失败，Console 里可能只报 _pickle.UnpicklingError: invalid load key, '_' 这类底层错误。
验证步骤：
- 按
Ctrl+Shift+P，运行Python: Select Interpreter，确认选中的解释器路径真实存在且可执行 - 在终端中运行该解释器，检查是否能 import
sys、os等内置模块 - 若用远程开发（SSH/WSL/Container），确保服务器端已安装
pylance插件，并且python.defaultInterpreter是远程路径（不是本地路径）
特别注意：远程场景下，如果工作区路径设为 /home 或 /，Pylance 可能因扫描过多系统包而卡死或崩溃，应限定到具体项目子目录。
项目结构或导入方式超出静态分析能力
跳转失败未必是配置问题，也可能是代码本身让语言服务器“看不懂”。Pylance 基于 AST 静态分析，对以下情况无能为力：
-
getattr(module, func_name_string)、importlib.import_module(name) - 使用字符串拼接构造模块名：
__import__(f"pkg.sub{version}") - 相对导入失效：
from .utils import helper但当前文件不在合法包内（缺__init__.py或未被解释器识别为包） - 多包开发时未配置
python.analysis.extraPaths，导致跨包导入无法解析
这类问题不会报错，但跳转会直接 fallback 到文本匹配——点不动或跳到错误位置。此时需重构导入逻辑，或显式添加路径配置，而非指望重启插件解决。
真正卡住人的，往往不是“没装插件”，而是 python.languageServer 被悄悄设成 "None"，或者工作区根本没以文件夹形式打开——这两个点不查，其他所有操作都是在绕远路。
