Pyright无法解析Poetry虚拟环境内已安装库的导入报错

故障特征 #

• 使用poetry管理虚拟环境，依赖已正常安装，代码在IPython中可正常运行
• 运行pyright同时触发reportMissingImports（导入无法解析）、reportGeneralTypeIssues（未知导入符号）两类错误
• 报错模块集中于谷歌云SDK、Protobuf生成的动态加载模块

排查步骤 #

1. 修复配置文件语法错误 #

当前pyrightconfig.json存在末尾引号不配对的JSON语法错误，会导致pyright无法正确读取虚拟环境配置，修正后完整配置如下：

{
  "venvPath": "/Users/jayed/Library/Caches/pypoetry/virtualenvs",
  "venv": "create-cluster-PmxHvHbg-py3.10",
  "pythonVersion": "3.10",
  "pythonPlatform": "Darwin",
  "useLibraryCodeForTypes": true
}

新增的useLibraryCodeForTypes参数配置pyright直接读取已安装第三方库的代码做类型推断，不依赖内置类型存根。

2. 验证虚拟环境识别状态 #

在项目根目录执行命令，强制指定pyright使用poetry虚拟环境的Python解释器扫描：

pyright --pythonpath /Users/jayed/Library/Caches/pypoetry/virtualenvs/create-cluster-PmxHvHbg-py3.10/bin/python .

若执行后导入错误消失，说明之前的配置未被正确加载，固定Python路径到编辑器的pyright插件配置即可。

3. 兼容谷歌云动态加载模块 #

本次报错的google.iam.v1、policy_pb2、assuredworkloads_v1等模块均为运行时动态生成/加载的代码，无静态Python文件供pyright扫描，按优先级选择以下方案解决：

• 优先安装官方类型存根：在激活的poetry环境中执行安装命令

  poetry add --dev types-protobuf types-google-cloud-iam google-cloud-stubs
  

  安装完成后清除pyright缓存重新扫描即可消除绝大多数报错：

  rm -rf ~/Library/Caches/pyright
  pyright .
  

• 个别残留报错可做精细化忽略：对确认运行正常的动态导入，可在对应代码行上方添加注释# pyright: reportMissingImports=false, reportGeneralTypeIssues=false做单行忽略，不建议全局关闭两类检查规则。

4. 版本兼容处理 #

若以上操作均无效，升级pyright到最新版本，当前使用的1.1.255版本发布于2022年，对动态导入、虚拟环境识别的支持存在已知缺陷：

npm install -g pyright@latest

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