Pyrefly 入门指南：新一代高速 Python 类型检查器
Pyrefly 是用 Rust 编写的 Python 静态类型检查器。本文讲解安装、项目初始化、配置、类型检查与 IDE 集成，并说明支持范围需按版本核对。
直接回答：Pyrefly 是一款以速度为核心的 Python 静态类型检查器：面向大型代码库和 IDE 反馈优化，具体耗时和类型支持需按版本及项目测试——它是 Mypy/Pyright 之后类型检查器性能竞赛的最新选手。
Pyrefly 的背景
Python 类型检查长期有个痛点：代码库一大，全量检查就要几十秒甚至几分钟，CI 与编辑器体验都打折扣。Pyrefly（Meta 开源，Rust 实现）专为大规模代码库设计——发布节奏和规模表现应查对应版本的发布记录，不能保证固定周一发版或秒级完成。
安装与初始化
pip install pyrefly # 或 uv add --dev pyrefly
cd myproject
pyrefly init # 生成配置文件
编辑器装对应插件（VS Code 扩展）后，保存即检查，错误波浪线即时出现。
第一次检查
# demo.py
def add(a: int, b: int) -> int:
return a + b
add("1", 2)
pyrefly check
# ERROR: Argument of type `str` is not assignable to parameter `a` of type `int`
全项目扫描默认开启，命令行检查与语言服务器的增量行为不同，耗时须在实际配置下测量。
配置
# pyproject.toml
[tool.pyrefly]
project-includes = ["src"]
project-excludes = ["tests/fixtures"]
python-version = "3.13"
按模块调整严格度（存量代码宽松、新代码严格）是落地标准动作：先把检查跑起来进 CI，再按模块逐步收紧，避免一次性面对上万条历史错误。
高级类型特性
Pyrefly 支持多种现代类型特性，仍需检查当前版本的支持范围：
- 泛型与 TypeVar：容器函数保类型；
- ** narrowing**：
isinstance/判空后类型自动收窄； - TypedDict / Literal / Final：结构化字典、枚举值、常量保护；
- 协议（Protocol）：结构化子类型（鸭子类型的静态版）。
from typing import Literal, Final
MAX_RETRY: Final = 3 # 再赋值会报错
def set_mode(mode: Literal["fast", "safe"]) -> None: ...
set_mode("turbo") # ERROR：不在允许值内
与 Mypy/Pyright 的关系
三家规则集高度重叠但判定细节有差异。常见姿势：CI 以一家为准（避免双标准扯皮），编辑器里 Pyrefly 提供速度体验。存量 Mypy 项目需核查插件、推断规则、存根和错误抑制，语法相同不代表低迁移成本。
常见问题（FAQ）
Q：Pyrefly 能完全替代 Mypy 吗？
A：规则覆盖已经相当全，但 共同依据是 Python typing 规范，不以单个检查器定义标准。新项目可以只用 Pyrefly；合规严格的团队保留 Mypy 做 CI 终审也不冲突。
Q：为什么我的存量项目一检查几百个错？
A：正常的"类型债"暴露。用配置排除老目录先行止血，新代码全注解，老代码随改动随补——覆盖率只升不降就是胜利。
Q：和 Ruff 或 ty 冲突吗？
A：Ruff 是 linter/formatter；Astral 的完整类型检查器是独立项目 ty，不是 Ruff 的 Beta 模式。应选定团队主检查器，另用 Ruff 检查代码规则。
官方参考
本文基于官方文档整理，未进行运行时或性能测试。示例中的业务函数、数据模型和部署地址需结合项目补全；局部片段不等同于完整生产应用。
