Pylance“未解析导入”是静态分析路径缺失所致，非代码错误；需配置pyrightconfig.json的extraPaths、确保__init__.py存在、选对解释器并重启语言服务器。
VSCode提示“未解析导入”不是代码写错了，而是Pylance语言服务器压根没找到你import的模块路径——它不执行代码，只静态扫描；所以运行没问题，但F12跳转失效、补全失灵、红波浪线满屏。
为什么选对解释器还报红？
解释器选对只是第一步。Pylance默认只看两个地方：site-packages 和工作区根目录。如果你的项目结构是 src/ 或 lib/ 下放模块，或者用 poetry/conda 管理环境但没激活对应 shell，Pylance 就会直接忽略那些目录。
- 右下角显示的 Python 路径必须指向真实激活的虚拟环境（如
/path/to/venv/bin/python），不能是系统全局 Python - 终端里
which python和 VSCode 状态栏显示的路径必须完全一致 - 切换 conda env 后，必须手动执行
Python: Select Interpreter，不能靠自动检测 - 用
poetry shell进入环境后，VSCode 仍可能沿用旧解释器，需重启窗口或重选
怎么让 Pylance 找到 src/ 或自定义包？
别只改 settings.json 里的 python.analysis.extraPaths，它容易被工作区设置覆盖，也不随项目迁移。最稳的方式是加 pyrightconfig.json 到项目根目录。
- 文件名必须是
pyrightconfig.json（不是tsconfig.json那套） -
extraPaths值是相对于该 JSON 文件所在目录的路径，比如项目根下有src/，就写"extraPaths": ["src"] -
src/目录下必须有__init__.py（哪怕空文件），否则 Pylance 不认为它是可 import 的包 - 如果模块在
tests/utils.py且你想从src/里import utils，就得把tests也加进extraPaths
相对导入（from .. import）为啥总标红？
Pylance 对相对导入极其严格：它要求当前文件必须处于一个“被识别为包”的上下文中，而不是当作脚本直接运行。
- 文件不能是双击运行的
python myscript.py，得用python -m package.myscript - 每一级父目录都得有
__init__.py，包括工作区根目录（除非你在pyrightconfig.json的include里显式覆盖） - 临时绕过方法：把
from ..utils import helper改成from myproject.utils import helper，再配extraPaths: ["."] - Jupyter Notebook 里相对导入基本无效，因为 kernel 启动方式和 Pylance 解析逻辑不一致
重启语言服务器还不生效？先查这三处
很多人点完 Python: Restart Language Server 就以为完事了，其实 Pylance 可能还在缓存旧路径。
- 打开命令面板（
Ctrl+Shift+P），运行Developer: Toggle Developer Tools，看 Console 里有没有Failed to resolve module类错误，确认具体缺哪个路径 - 检查
.vscode/settings.json是否存在冲突配置，比如同时写了python.defaultInterpreterPath和python.venvPath，后者会覆盖前者 - 删掉
.pyright缓存目录（位于项目根或用户目录下），强制重建符号索引
真正麻烦的从来不是路径本身，而是 Pylance 的缓存机制和多层配置叠加后的隐式行为——它不会告诉你哪一层配置赢了，只会默默标红。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
