Pyright 入门指南：微软出品的 Python 类型检查器
Pyright 是微软开发的快速 Python 静态类型检查器（Pylance 的内核）。本文讲解安装配置、类型检查原理、高级注解、类型收窄与 Final/Literal 的用法。
直接回答：Pyright 是微软用 TypeScript 打造的 Python 静态类型检查器，也是 VS Code 里 Pylance 的分析内核：检查速度快、规则严格、类型收窄智能——可与 VS Code 工作流结合，仍需配置和逐步处理诊断。
Pyright 的生态位
Mypy 与 Pyright 都实现 Python 类型规范，推断细节和插件支持有区别；Pyright 提供面向编辑器的增量分析，耗时需按项目测量。你在 VS Code 里看到的红色波浪线，背后就是它。命令行版本可独立跑 CI。
安装与起步
npm install -g pyright # 微软官方 CLI 分发方式
# pip install pyright 是第三方 Python 包装器，需核对来源与版本
# calc.py
def divide(a: float, b: float) -> float:
return a / b
result = divide("10", 2) # 类型错误
pyright calc.py
# error: Argument of type "str" cannot be assigned to parameter "a" of type "float"
配置文件
pyrightconfig.json：
{
"include": ["src"],
"exclude": ["**/node_modules", "tests/fixtures"],
"pythonVersion": "3.13",
"typeCheckingMode": "strict",
"reportMissingImports": true
}
typeCheckingMode 有 off/basic/standard/strict 四档。存量项目从 basic 起步，新模块直接 strict。
理解 Pyright 的检查风格
Pyright 以"严格但讲理"著称：
- 未注解函数默认参数为 公开资料未说明（strict 下视为告警源）；
- 可选值必须先判空再使用；
- 类型推断极其积极——
x = []会被推断为list[公开资料未说明]并要求你补注解。
def get_first(items: list[str]) -> str | None:
return items[0] if items else None
name = get_first(["a"])
name.upper() # ERROR：name 可能是 None
if name:
name.upper() # OK：收窄后为 str
类型收窄的高级玩法
from typing import TypeGuard
def is_int_list(val: list[object]) -> TypeGuard[list[int]]:
return all(isinstance(x, int) for x in val)
def handle(data: list[object]):
if is_int_list(data):
sum(data) # 此处 data 已是 list[int]
isinstance、assert、match 语句都能触发收窄——Pyright 对模式匹配的类型推断支持尤其出色。
Final 与 Literal：把约定变成硬约束
from typing import Final, Literal
TIMEOUT: Final = 30 # 任何再赋值都是错误
def log(level: Literal["debug", "info", "warn"], msg: str): ...
log("trace", "x") # ERROR：非法字面量
配置常量用 Final，状态枚举用 Literal——比起跑起来的 ValueError，编辑器里的红波浪线便宜得多。
常见问题（FAQ）
Q：Pyright 和 Mypy 结果不一致听谁的？
A：两者对 PEP 的解读偶有分歧。团队定一家做 CI 标准（依据项目需求选定，不代表某个检查器是规范裁决者），编辑器里用 Pyright 求速度体验。注解写法保持两家兼容。
Q：strict 模式太严格落地不了？
A：按目录覆盖配置：核心模块 strict，其余 basic，逐步推进。# pyright: strict 文件级指令也行。
Q：和 Pyrefly 比呢？
A：Pyrefly 使用 Rust，实际速度和规则兼容性需在项目上评估；Pyright 成熟稳定、VS Code 原生。都是好东西，选与团队工具链咬合更紧的。
官方参考
本文基于官方文档整理，未进行运行时或性能测试。示例中的业务函数、数据模型和部署地址需结合项目补全；局部片段不等同于完整生产应用。
