如何为Neovim中的PyRight LSP配置已有Stub文件？

API 探路者

2026-7-16

让PyRight加载自定义Stub文件的正确操作步骤

先捋顺Stub目录结构
你的mystub得是标准Python包结构——必须包含__init__.pyi，内部的.pyi文件名要和目标模块对应（比如object.pyi对应object模块），这是PyRight能识别的基础。
正确配置pyrightconfig.json的stubPath
stubPath要指向存放Stub包的父目录，而非Stub包本身。举个实际例子：
假设你的项目目录结构如下：
```
项目根目录/
  代码文件夹/
    你的代码.py
  自定义Stub文件夹/
    mystub/
      __init__.pyi
      object.pyi
      ...
```
把pyrightconfig.json放在项目根目录中，内容写为：
```
{
  "stubPath": "./自定义Stub文件夹"
}
```
这样PyRight会自动在自定义Stub文件夹下扫描所有符合结构的Stub包，包括你的mystub。
推荐优化：将Stub包命名为xxx-stubs格式
PyRight默认优先识别xxx-stubs命名的Stub包（比如把mystub改成mystub-stubs），如果你的Stub是为名为mystub的第三方库准备的，重命名后放在stubPath指向的目录下，PyRight会自动关联Stub与对应库，无需额外配置。
目录结构示例：
```
项目根目录/
  自定义Stub文件夹/
    mystub-stubs/
      __init__.pyi
      object.pyi
      ...
```
对应的pyrightconfig.json配置和上面一致即可。
验证Stub是否生效
在Neovim中打开你的Python代码，尝试引用mystub模块内容，如果能弹出正确的类型提示，说明Stub加载成功。也可以在项目目录下运行pyright --verbose 你的代码.py，查看日志中是否有加载mystub相关Stub的记录。
常见问题排查
- 确保pyrightconfig.json放在项目根目录，PyRight只会自动识别根目录下的配置文件。
- 检查.pyi文件的语法，若存在类型注解错误，PyRight可能直接忽略该Stub。
- 若为全局安装的PyRight，需在项目目录下运行pyright命令，否则可能无法识别本地配置和Stub。