Pylance报红但代码能运行，因其仅静态分析路径而非执行代码；常见原因包括项目结构未识别、extraPaths未配置、相对导入使用不当；解决需配pyrightconfig.json、确保__init__.py存在、重启语言服务器并确认解释器。
为什么 import 报红但代码能正常运行？
Pylance 的 “unresolved import” 不代表 Python 解释器会报错，它只是静态分析时找不到模块路径。常见于：项目结构没被识别、pyrightconfig.json 或 settings.json 里没配对的 extraPaths、用相对导入但当前文件没被当作包入口启动。
- Pylance 默认只扫描工作区根目录和已安装的 site-packages
- 如果你有
src/目录或tests/目录下直接跑脚本，Pylance 很可能不知道那里也能 import - 虚拟环境切换后没重载 Pylance，也会卡在旧路径上
检查方法：打开命令面板（Ctrl+Shift+P），运行 Python: Select Interpreter，确认选中的是你实际运行代码的那个环境。
怎么让 Pylance 找到 src 或自定义包路径？
最常用也最稳的方式是加 pyrightconfig.json 文件到工作区根目录，比改 VSCode 设置更可靠、更易复现。
- 文件必须叫
pyrightconfig.json（不是tsconfig.json那套） - 内容示例：
{ "include": ["**/*.py"], "exclude": ["**/node_modules", "**/__pycache__"], "extraPaths": ["src", "lib", "tests"] } -
extraPaths是相对于该配置文件所在目录的路径，不是相对于 Python 文件 - 如果用了
src结构，记得确保src下有<strong>init</strong>.py（哪怕为空），否则 Pylance 不认为它是可 import 的包
不推荐只靠 VSCode 的 "python.defaultInterpreterPath" 或 "python.analysis.extraPaths" 设置——它们容易被工作区设置覆盖，且不同用户打开时行为不一致。
立即学习“Python免费学习笔记（深入）”；
相对导入（from ..utils import helper）为啥总报错？
Pylance 对相对导入非常严格：它要求文件必须处于一个“被识别为包”的上下文中，即：
- 当前文件不能是直接执行的脚本（比如你双击运行
python myscript.py） - 它得通过
-m方式运行，例如python -m package.submodule - 对应的目录结构里每一级都得有
<strong>init</strong>.py - 工作区根目录或
pyrightconfig.json中的include必须覆盖到整个包路径
简单绕过法：把想测试的模块临时改成绝对导入，比如 from myproject.utils import helper，再配合 extraPaths 指向 myproject 所在目录。
重启和重载不生效？先查这三个地方
Pylance 不是改完就立刻刷新的，尤其路径类配置变更后常缓存旧状态。
- 关闭所有 VSCode 窗口，再重新打开工作区（仅 reload window 不够）
- 在命令面板运行
Developer: Reload Window后，再运行Python: Restart Language Server - 看右下角 Python 环境状态栏，确认显示的是你期望的解释器路径；如果显示 “No interpreter selected”，Pylance 基本不会解析任何自定义路径
还有一个隐蔽坑：某些项目用了 setup.py 或 pyproject.toml 声明了 packages，但没安装为 editable 模式（即没运行 pip install -e .）。这种情况下，即使路径配对了，Pylance 也可能跳过未安装的本地包。
Pylance 的路径解析逻辑比直觉中更“静态”，它不运行代码也不读 sys.path，全靠配置推断。所以别指望它自动理解 os.chdir() 或动态插入路径的操作。
