如何让Pylance识别同目录下的Python类型存根（.pyi）文件

1. 先确认项目结构规范 #

Pylance默认优先识别同目录.pyi文件，但严格模式下可能因结构不规范失效，确保你的项目结构符合以下形式：

your-library/
├── src/
│   ├── your_module/
│   │   ├── __init__.py
│   │   ├── core.py
│   │   └── core.pyi  # 同目录同名存根文件
└── pyrightconfig.json

2. 精准配置pyrightconfig.json #

之前的配置可能不够针对性，直接用以下配置覆盖，重点明确存根搜索路径：

{
  "include": ["src/**/*"],
  "exclude": ["**/__pycache__", "**/*.pyc"],
  "stubPath": ".",  // 核心：将项目根目录设为存根搜索源，递归扫描所有子目录的.pyi
  "strict": true,
  "typeCheckingMode": "strict",
  "pythonVersion": "3.10",  // 匹配你的项目Python版本
  "pythonPlatform": "Linux"  // 匹配devcontainer运行平台
}

如果只想限定特定目录的存根，可把stubPath设为具体路径，比如"src/your_module"。

3. 调整VS Code的Pylance专属设置 #

在devcontainer内的.vscode/settings.json中添加以下配置，强制Pylance优先读取自定义存根：

{
  "python.analysis.typeCheckingMode": "strict",
  "python.analysis.stubPath": ".",
  "python.analysis.include": ["src/**/*"],
  "python.analysis.exclude": ["**/__pycache__"],
  // 关闭自动生成存根，避免覆盖自定义.pyi文件
  "python.analysis.useLibraryCodeForTypes": false
}

useLibraryCodeForTypes是关键——严格模式下Pylance可能自动生成临时存根，关闭后会强制读取你编写的.pyi。

4. 检查存根语法兼容性 #

Mypy对存根语法的容忍度比Pyright高，确认你的.pyi符合Pyright要求：

• 存根中的函数签名、类定义必须和对应.py文件完全匹配（包括参数名、返回值类型）
• 存根中只保留类型标注，不能写可执行代码
• 比如.py文件里是def compute(a: int) -> str，.pyi不能写成def compute(a) -> str

5. 强制刷新Pylance缓存 #

VS Code中按Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（Mac），执行两个命令：

• Python: Restart Language Server
• Developer: Reload Window
  清除缓存避免旧配置残留导致的识别问题。

6. 排查devcontainer环境冲突 #

如果以上都无效，检查devcontainer环境：

• 确认Pylance使用的是devcontainer内的Python解释器，而非本地环境
• 检查devcontainer中是否安装了types-*类包，这类包可能和自定义存根冲突

内容的提问来源于stack exchange，提问作者bbebin