Pyright 指南：为 Python 代码提供快速的静态类型检查

类型提示让 Python 代码更易理解和维护。但问题在于：仅有提示并不能捕获错误。您需要一个类型检查器来验证代码是否真的遵循了您声明的类型。

我在生产环境中用过 Mypy 和 Pyright。Pyright 的速度优势在开发过程中最明显。类型错误会在您输入时出现，而不是保存后。在大型代码库中，这种更快的反馈循环会带来实实在在的差异。

本教程涵盖高效使用 Pyright 所需的一切。我将演示如何安装它、为您的项目配置它，以及将其与 VS Code 集成。我也会梳理 Pyright 与 Mypy 之间的差异。

什么是 Pyright？

Pyright 是由微软开发的 Python 静态类型检查器。它读取您的代码，分析类型注解，并在类型不匹配时报告错误。与在代码执行时捕获错误的运行时检查不同，静态分析会在您运行任何东西之前就将其捕获。

虽然大多数 Python 工具使用 Python 编写，但 Pyright 使用 TypeScript 编写并运行在 Node.js 上。对于一个 Python 工具来说，这似乎是个奇怪的选择，对吧？但这正是 Pyright 如此之快的原因。V8 JavaScript 引擎的执行速度远快于 CPython。

您会以两种方式接触 Pyright。您可以在 CI/CD 流水线中以命令行工具的方式运行它，在合并前捕获类型错误。或者您可能已经在无意间使用它了。它是微软 VS Code Python 扩展 Pylance 的引擎。那些类型错误下方的红色波浪线？那是 Pyright 在幕后工作。

该工具内置了 Python 标准库和常见包的类型桩。检查使用 os、 json或 typing 的代码不需要额外安装。对于第三方包，Pyright 会使用社区维护的 typeshed 类型桩，或您单独安装的特定包类型桩。

如何安装 Pyright

现在让我们在您的系统上运行 Pyright。您有两种安装方式：npm（原生方式）或 pip（Python 包装器）。

用 npm 安装 Pyright

推荐使用 npm 安装，因为 Pyright 运行在 Node.js 上。您需要 Node.js 版本 14.0.0 或更高。

# Global installation
npm install -g pyright

# Run without installing globally
npx pyright

# Local project installation
npm install --save-dev pyright技术支持

我会用全局安装来做快速检查，用本地安装用于需要锁定版本的项目。npx 方式适合一次性使用，而无需增加全局包。

通过 Python 包装器安装 Pyright

如果您的团队只使用 Python，且不希望在工具链中引入 Node.js，可以使用一个 PyPI 包装器：

# Standard installation
pip install pyright

# Recommended: includes Node.js automatically
pip install pyright[nodejs]技术支持

该包装器会检查系统上是否有 Node.js。如果缺失，包装器会自动下载独立版本。[nodejs] 额外选项使用比默认更可靠的下载方式。

请注意权衡。首次运行会因下载依赖而更慢。网络受限的 CI 环境可能失败。而且 PyPI 版本有时会比 npm 发布滞后几天。

对大多数 Python 团队来说，这个包装器足够好用。但如果遇到问题，请回退到 npm 安装，它更可靠。

在 Python 项目中运行 Pyright

安装完成后，运行 Pyright 很简单。进入您的项目目录并运行：

pyright技术支持

就这么简单。Pyright 会扫描 Python 文件，对其进行分析，并报告发现的类型错误。无需复杂设置。

Pyright 默认会检查什么

Pyright 会检查哪些内容？在没有任何配置的情况下，它会执行多项检查。它会验证类型注解是否与实际用法匹配；捕获未定义变量和不可达代码；校验导入是否正确；并标记明显的类型不匹配，比如在需要整数的地方传入字符串。

下面是一个包含错误的项目的示例输出：

/src/utils.py:12:15 - error: Argument of type "str" cannot be assigned 
   to parameter "count" of type "int" in function "process_items"
   "str" is not assignable to "int" (reportArgumentType)
/src/main.py:45:9 - error: "user" is possibly unbound (reportPossiblyUnbound)
2 errors, 0 warnings, 0 informations技术支持

每个错误都会显示文件路径、行号、列号和描述。括号中的规则名（如 reportArgumentType）会准确告诉您是哪项检查触发了错误。这在您想屏蔽特定规则时很重要。我们稍后会介绍。

理解退出码

Pyright 会根据结果返回不同的退出码：

在 CI 流水线中，您通常希望在退出码 1 时让构建失败。退出码 2–4 表示工具本身出了问题，而非您的代码。

配置 Pyright

虽然 Pyright 开箱即用，但真实项目需要自定义。您会希望指定要检查的文件、目标 Python 版本，以及分析的严格程度。让我们看看关键配置选项。

类型检查模式

Pyright 提供四个严格级别。您选择的模式决定启用了多少规则。

应选择哪个模式？对于新项目，从standard 模式开始。它能捕获真实错误而不至于让您被错误淹没。处理遗留代码？Basic 模式更适合逐步引入类型时使用。将strict 模式保留给库和关键基础设施，在那里您需要最大安全性。

提醒一下：从 standard 跳到 strict 的跨度很大。strict 模式会启用大约 30 条额外规则，包括要求所有函数参数和返回值都有类型注解。切换后预期报告的错误数量会增加 10 倍。我就是这么吃过亏的。

strict 模式要求完整的类型注解。图片来源：作者

配置文件

Pyright 会从 pyrightconfig.json 或 pyproject.toml 中读取配置。如果两者同时存在，pyrightconfig.json 优先生效。

以下是一个最小的 pyrightconfig.json：

{
  "include": ["src"],
  "exclude": ["**/node_modules", "**/__pycache__", "**/.venv"],
  "pythonVersion": "3.12",
  "typeCheckingMode": "standard"
}技术支持

在 pyproject.toml 中的等价配置：

[tool.pyright]
include = ["src"]
exclude = ["**/node_modules", "**/__pycache__", "**/.venv"]
pythonVersion = "3.12"
typeCheckingMode = "standard"技术支持

配置文件控制 Pyright 的行为。图片来源：作者。

这里有个关键细节常让人踩坑：如果您手动定义了 exclude，它会完全 替换默认值。自定义排除模式中务必包含 node_modules、 __pycache__ 和您的虚拟环境。否则，Pyright 会尝试分析您的依赖，导致大幅变慢。相信我，您不会想等 10 分钟才完成一次类型检查。

虚拟环境配置

Pyright 如何找到您安装的包？您需要告诉它去哪里找。通过 venvPath 和 venv 来配置：

{
  "venvPath": ".",
  "venv": ".venv"
}技术支持

这会告诉 Pyright 在 ./.venv 中查找包。如果您的虚拟环境位置不同，请相应调整。否则，Pyright 无法找到您已安装的依赖，并会对所有内容报告导入缺失错误。

抑制诊断

有时 Pyright 在技术上是正确的，但您仍需要屏蔽特定错误。也许您在处理遗留代码，或者在特定情况下您比类型检查器更了解。您可以在三个层级抑制错误。

配置级抑制

全局禁用规则：

{
  "reportMissingTypeStubs": "none",
  "reportUnusedVariable": "warning"
}技术支持

文件级抑制

在文件顶部添加注释：

# pyright: basic
# pyright: reportPrivateUsage=false技术支持

行级抑制

仅抑制单行：

x: int = "hello"  # type: ignore
x: int = "hello"  # pyright: ignore
x: int = "hello"  # pyright: ignore[reportAssignmentType]技术支持

当您想只静音某一项检查而不禁用同一行上的其他检查时，特定规则语法（[reportAssignmentType]）很有用。

配置讲完了，接下来看看 Pyright 如何与您的开发环境集成。

Pyright 在 VS Code 和各类 IDE 中的使用

如果您和大多数 Python 开发者一样，您会通过 Pylance 而不是命令行来体验 Pyright。理解两者的关系有助于正确配置编辑器并避免常见陷阱。

Pyright 与 Pylance

Pylance 是微软的 VS Code 扩展，捆绑了 Pyright 的类型检查引擎。安装 Pylance 即可自动获得 Pyright。但 Pylance 还增加了开源 Pyright 不具备的功能：

• 语义高亮：按类型为变量着色
• 高级自动导入：更智能的导入建议
• 代码导航：“在工作区中查找所有引用”

这些功能是闭源的，仅在 VS Code 中可用。如果您使用 Neovim、Emacs 或其他编辑器，您将获得 Pyright 的核心功能，但没有这些附加项。

Pylance 会在编辑器中高亮显示类型错误。图片来源：作者。

必备 VS Code 设置

通过 VS Code 设置配置 Pylance：

{
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "standard",
  "python.analysis.diagnosticMode": "openFilesOnly"
}技术支持

diagnosticMode 设置会影响性能。 "openFilesOnly" 仅分析您已打开的文件。 "workspace" 会分析整个工作区，但会使用更多内存和 CPU。

常见配置陷阱

解释器选择很重要。 Pylance 使用您选择的 Python 解释器来定位已安装的包。如果您明明已安装的包突然报错，请在 VS Code 状态栏检查是否选择了正确的解释器。

解释器选择会影响包的发现路径。图片来源：作者。

CLI 与 Pylance 的默认值不同。 Pylance 将 typeCheckingMode 默认设为 "off"，而 CLI 的默认是 "standard"。Pylance 还会自动将 src 加入搜索路径；CLI 则不会。若要在编辑器与 CI 之间保持一致，请在 pyproject.toml 中显式设置所有选项。

“代码变灰”现象。Pylance 会基于类型分析将不可达代码置灰。如果代码意外变灰，请检查其前面紧接调用的函数。若某个函数的返回类型标注为 NoReturn ，则其后的所有代码都会显示为不可达。

Pyright 与 Mypy：各自适用场景

您可能会问：我该用 Pyright 还是继续用 Mypy？两者都已达生产可用，选择取决于您的工作流和需求。下面我来拆解关键差异。

速度与响应性

Pyright 在完整项目扫描中大约比 Mypy 快 3–5 倍，而在增量检查中几乎是即时的。这在开发时尤为重要，因为您希望立刻获得反馈。

Mypy 有一个守护进程模式（dmypy）能改善性能，但仍较慢，且偶尔会出现缓存问题需要重启。

类型推断差异

有趣的地方在这里。两个工具的类型推断不同。看这段代码：

coordinates = (10, 20)技术支持

Pyright 推断为 tuple[Literal[10], Literal[20]]，保留精确值，因为元组是不可变的。Mypy 则推断为 tuple[int, int]，将其泛化为通用类型。

Pyright 的做法能捕获更多错误，但在函数期望通用类型时偶尔会造成摩擦。实际上这很少成为问题，因为 Literal[10] 是 int 的有效子类型。

未注解代码分析

这是最大的实际差异，对遗留代码库来说可谓“改变游戏规则”。Mypy 默认跳过未注解的函数。Pyright 则仍会分析它们，即便没有类型提示也能捕获明显错误。

对于注解稀少的遗留代码库，Pyright 可充当强力 linter，能捕获未定义变量和不可能的方法调用。Mypy 则将这些函数视为“动态”而忽略它们。

插件支持

Mypy 支持针对 Django、SQLAlchemy 等框架的插件。这些插件能理解 ORM 的“魔法”，并为动态生成的属性提供准确类型。

Pyright 没有插件系统，完全依赖类型桩。到 2026 年，大多数主流库已有高质量类型桩，因此这点不再像过去那样重要。但如果您使用大量元编程的框架，请在决定使用 Pyright 前确认是否存在高质量类型桩。

在开发中使用 Pylance（Pyright）获取即时反馈；如果您的项目使用框架插件，考虑在 CI 中同时运行 Pyright 和 Mypy。

使用 Pyright 时的常见问题

当 Pyright 报告出乎意料的错误时，原因通常是以下这些。

缺少类型桩

见过这类错误吗？当找不到某个包的类型信息时，Pyright 会抱怨：

Import "requests" could not be resolved (reportMissingImports)技术支持

缺少类型桩会触发导入警告错误。图片来源：作者。

首先，检查该包是否安装在您的虚拟环境中，以及 Pyright 是否知道到哪里查找（使用前面介绍的 venvPath 和 venv 设置）。

如果包已安装但缺少类型信息，请安装社区类型桩：

pip install types-requests types-PyYAML types-redis技术支持

对于没有可用类型桩的包，您有两个选项。可以在配置中使用 "reportMissingTypeStubs": "none" 来禁用警告；或者自己生成草稿类型桩：

pyright --createstub some_package技术支持

这会创建一个骨架 .pyi 文件，您可以把实际使用的方法补充进去。

pre-commit 钩子失败

Pyright 在本地可用，但在 pre-commit 钩子中失败？问题通常出在环境隔离。Pre-commit 会在隔离环境中运行钩子，无法看到您项目中已安装的包。

通过将钩子指向您的虚拟环境来修复：

repos:
  - repo: https://github.com/RobertCraigie/pyright-python
    rev: v1.1.408
    hooks:
      - id: pyright
        args: ["--venvpath", ".", "--venv", ".venv"]技术支持

出乎意料的 strict 模式错误

启用 strict 模式后突然看到成千上万的错误？别慌。这很正常。strict 模式要求完整的类型注解。请从 basic 或 standard 模式开始，逐步添加注解，只在完全注解完的模块上启用 strict。

使用按文件的注释，让遗留代码保持在宽松模式：

# pyright: basic技术支持

这样您就能对新代码实施严格检查，同时逐步迁移旧代码。

除了排障之外，以下策略将从一开始就让您的 Pyright 体验更顺畅。

使用 Pyright 的最佳实践

在不同项目中使用 Pyright 后，我总结出一些能让采用过程更顺利的做法。采纳这些编码最佳实践可以确保类型检查助力而非添堵。

从 standard 模式开始。如前所述，它能捕获真实错误且不要求完整注解。您随时可以再收紧规则。

固定 Pyright 版本。Pyright 发布频繁，新版本有时会标记此前通过的代码。在 CI 中，未固定版本的 pip install pyright 可能因周末发布导致周一早上构建失败。我经历过，真的不妙。

[tool.pyright]
# In pyproject.toml
pythonVersion = "3.12"技术支持

# In requirements-dev.txt
pyright==1.1.408技术支持

逐步修复错误。不要试图一次性消除 10,000 个错误。使用 strict 数组仅对特定目录启用严格检查：

{
  "typeCheckingMode": "standard",
  "strict": ["src/core", "src/api"]
}技术支持

尽早使用配置文件。即便是小项目，显式配置也能避免意外。花五分钟记录您的 Python 版本、虚拟环境路径和选择的严格级别。未来的您会感谢现在的自己。

不要一开始就追求完美。先大量使用 # pyright: ignore 。这能将技术债务清晰标注出来，让您逐步清理，而不是阻碍进度。采用新工具时，“完美”是“良好”的敌人。