VS Code中Pylance指定stubPath后跨目录Stub文件无法被识别

安全阿岳

2026-7-13

解决Pylance中Stub文件放在子目录无法生效的问题

当把Stub文件放在模块内的typings子目录时，Pylance无法自动关联到对应的源码模块，导致IntelliSense提示错误。核心原因是Stub文件的目录结构未与源码包层级匹配，同时stubPath配置需对应Stub文件的根目录。

调整Stub文件的目录结构
保持Stub文件的包层级与源码完全一致，推荐将Stub文件统一放在工作区根目录的typings文件夹下，修改后的文件结构如下：
```
test/
  typings/
    foo/
      foo.pyi
  foo/
    foo.py
  test.py
```
若坚持把typings放在foo模块内，结构需调整为：
```
test/
  foo/
    typings/
      foo/
        foo.pyi
    foo.py
  test.py
```
配置python.analysis.stubPath
在VS Code的settings.json中指定Stub文件的根目录：
- 使用根目录typings时：
```
"python.analysis.stubPath": "./typings"
```
- 使用模块内typings时：
```
"python.analysis.stubPath": "./foo/typings"
```
使配置生效
按下Ctrl+Shift+P打开命令面板，选择「Reload Window」重启VS Code窗口，此时IntelliSense会正确识别Stub文件中的类型定义，from foo.foo import Foo将显示class Foo的提示，而非默认的object类型。