Nvim中Python LSP（Pyright）错误诊断异常求助

你遇到的Pyright诊断错误，核心原因是Neovim中Pyright运行在单文件模式（从LspInfo的Running in single file mode可确认），而VSCode里Pyright会自动识别项目根目录并加载完整的类型上下文，两者的类型推断环境不一致。

单文件模式下，Pyright无法获取项目中models.File、schema.File的完整类型定义，也无法正确解析SQLAlchemy查询的返回类型，因此把db.query(...).first()的推断类型判定为Any | None，与你声明的返回类型schema.File冲突。

1. 让Pyright识别项目根目录（优先推荐） #

在项目根目录创建pyrightconfig.json文件，指定项目范围，让Pyright退出单文件模式：

{
  "include": ["**/*.py"], // 匹配项目内所有Python文件，可根据实际目录调整
  "exclude": ["venv/**/*"] // 排除虚拟环境目录
}

或者如果项目已有pyproject.toml，直接添加Pyright配置：

[tool.pyright]
include = ["src"]  // 替换为你的源码目录
exclude = ["venv"]

配置完成后重启Neovim的LSP服务，Pyright会加载项目完整类型信息，错误提示会自动消失。

2. 修正函数类型注解（符合类型规范） #

如果函数逻辑上可能返回None（比如找不到对应文件时），应明确更新返回类型：

def get_info_about_file(db: Session, name_of_file: str) -> schema.File | None:
    return db.query(models.File).filter(models.File.name == name_of_file).first()

如果业务逻辑保证文件一定存在，可通过断言或类型强制转换告诉Pyright结果非空：

# 方式1：断言（推荐，同时做运行时检查）
def get_info_about_file(db: Session, name_of_file: str) -> schema.File:
    result = db.query(models.File).filter(models.File.name == name_of_file).first()
    assert result is not None, f"文件 {name_of_file} 不存在"
    return result

# 方式2：类型强制转换
from typing import cast
def get_info_about_file(db: Session, name_of_file: str) -> schema.File:
    return cast(schema.File, db.query(models.File).filter(models.File.name == name_of_file).first())

3. 临时忽略错误（应急方案） #

如果不想修改代码或项目配置，可在Pyright配置中关闭该类型检查：
在pyrightconfig.json中添加：

{
  "reportReturnTypeMismatch": false
}

或在单个函数上方添加注释忽略：

# pyright: ignore[reportReturnTypeMismatch]
def get_info_about_file(db: Session, name_of_file: str) -> schema.File:
    return db.query(models.File).filter(models.File.name == name_of_file).first()

4. 完善类型依赖支持 #

确保安装了SQLAlchemy的类型提示依赖，帮助Pyright更好地推断查询结果类型：

# SQLAlchemy 1.x版本安装类型存根
pip install sqlalchemy-stubs
# SQLAlchemy 2.0+自带类型提示，确保升级到最新版本
pip install --upgrade sqlalchemy

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