执行pyright时出现typing.py及自定义代码未定义变量错误

问题现象 #

执行pyright时出现大量内置类型（int、str、frozenset等）未定义的错误，具体输出如下：

/opt/homebrew/bin/pyright /Users/pli/Desktop/develop/app/application/router/test.py
/Users/pli/Desktop/develop/app/application/router/test.py
  /Users/pli/Desktop/develop/app/application/router/test.py:21:11 - error: "int" is not defined (reportUndefinedVariable)
  /Users/pli/Desktop/develop/app/application/router/test.py:22:16 - error: "int" is not defined (reportUndefinedVariable)
  /Users/pli/Desktop/develop/app/application/router/test.py:23:15 - error: "str" is not defined (reportUndefinedVariable)
  /Users/pli/Desktop/develop/app/application/router/test.py:24:13 - error: "str" is not defined (reportUndefinedVariable)
  /Users/pli/Desktop/develop/app/application/router/test.py:33:39 - error: "int" is not defined (reportUndefinedVariable)

/opt/homebrew/cellar/python@3.11/3.11.4_1/frameworks/python.framework/versions/3.11/lib/python3.11/typing.py
  /opt/homebrew/cellar/python@3.11/3.11.4_1/frameworks/python.framework/versions/3.11/lib/python3.11/typing.py:363:54 - error: "frozenset" is not defined (reportUndefinedVariable)
  /opt/homebrew/cellar/python@3.11/3.11.4_1/frameworks/python.framework/versions/3.11/lib/python3.11/typing.py:2850:15 - error: "frozenset" is not defined (reportUndefinedVariable)
  /opt/homebrew/cellar/python@3.11/3.11.4_1/frameworks/python.framework/versions/3.11/lib/python3.11/typing.py:2854:12 - error: "frozenset" is not defined (reportUndefinedVariable)/opt/homebrew/cellar/python@3.11/3.11.4_1/frameworks/python.framework/versions/3.11/lib/python3.11/typing.py:2920:15 - error: "type" is not defined (reportUndefinedVariable)
  /opt/homebrew/cellar/python@3.11/3.11.4_1/frameworks/python.framework/versions/3.11/lib/python3.11/typing.py:3068:14 - error: "type" is not defined (reportUndefinedVariable)
  /opt/homebrew/cellar/python@3.11/3.11.4_1/frameworks/python.framework/versions/3.11/lib/python3.11/typing.py:2929:22 - error: "type" is not defined (reportUndefinedVariable)
  /opt/homebrew/cellar/python@3.11/3.11.4_1/frameworks/python.framework/versions/3.11/lib/python3.11/typing.py:488:16 - error: "type" is not defined (reportUndefinedVariable)
  /opt/homebrew/cellar/python@3.11/3.11.4_1/frameworks/python.framework/versions/3.11/lib/python3.11/typing.py:2728:15 - error: "dict" is not defined (reportUndefinedVariable)
  /opt/homebrew/cellar/python@3.11/3.11.4_1/frameworks/python.framework/versions/3.11/lib/python3.11/typing.py:1558:16 - error: "isinstance" is not defined (reportUndefinedVariable)
  /opt/homebrew/cellar/python@3.11/3.11.4_1/frameworks/python.framework/versions/3.11/lib/python3.11/typing.py:1561:18 - error: "tuple" is not defined (reportUndefinedVariable)

已尝试操作 #

• 通过Homebrew重装pyright并重新执行
• 在PyCharm设置中重置文件监听器

相关代码片段（test.py） #

from fastapi import APIRouter, Header, Query
...

router = APIRouter(tags=["Test"])

@router.get("/api/v1/test/{id_}")
async def get_test_(id_: str) -> TestResponse | None:
    return await get_test(id_=id_)


@router.post("/api/v1/test/")
async def add_email_paste_parsing_info_(
    data: TestRequest, operator_id: int = Header(include_in_schema=False)
) -> TestResponse:
    return await add_email_paste_parsing_info(data, operator_id)

排查与解决步骤 #

1. 指定pyright关联的Python版本
   运行pyright --python-version 3.11明确指定Python版本，若项目使用虚拟环境，可通过pyright --pythonpath /path/to/your/virtualenv/bin/python指定解释器路径。

2. 检查项目pyright配置文件
   项目根目录若存在pyrightconfig.json，确认其中pythonVersion、pythonPath配置是否匹配当前使用的Python环境。无配置文件时可新建基础配置：

   {
     "pythonVersion": "3.11",
     "pythonPath": "/opt/homebrew/bin/python3.11"
   }
   

3. 清除pyright缓存
   缓存损坏可能导致类型识别异常，删除缓存目录：

   • macOS/Linux: 执行rm -rf ~/.cache/pyright
   • Windows: 删除%USERPROFILE%\.cache\pyright文件夹

4. 验证Python安装完整性
   运行python3.11 -c "print(int, str, frozenset)"，若输出正常说明Python本身无问题；若报错，重装Python@3.11：

   brew uninstall python@3.11 && brew install python@3.11
   

5. 安装最新版pyright
   Homebrew版本可能滞后，可通过npm安装全局最新版（需系统有Node.js环境）：

   npm install -g pyright
   

   之后用全局安装的pyright重新执行检查。

6. 确认PyCharm解释器配置
   打开PyCharm的File > Settings > Project: [项目名] > Python Interpreter，确认选择的解释器为正确的Python 3.11版本，路径与系统中一致。

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