📌 项目地址：facebook/pyrefly | ⭐ 6,174 颗星 | 🔧 Rust | 📜 未标注
一件事说明白它做了什么
Pyrefly 是 Facebook（现 Meta）开源的 Python 类型检查器 + LSP 语言服务器。底层用 Rust 实现，速度和准确性都压过了 Mypy 和 Pyright。官方数据：单机每秒处理 185 万行代码，检查 PyTorch 比 Mypy 和 Pyright 快 15 倍。在编辑器里，保存文件后重检通常在 10 毫秒内完成。
我打开官方沙盒（https://pyrefly.org/sandbox/）敲了几行代码，类型错误几乎是跟着敲击一起出现的，没有肉眼可见的延迟。CLI 模式跟编辑器 LSP 模式的结果完全一致 —— 这意味着你不会遇到“CI 里不报错，编辑器里报错”的割裂情况。
核心优势：不妥协的速度
Pyrefly 快的秘密不只是 Rust 语言，还有它对类型推断路径的优化。它没有砍掉属性推断、泛型、重载这些特性来换速度，而是通过更聪明的调度和增量检查来减少重复计算。官方给的基准测试是 PyTorch 的代码库 —— 这是真实的大型项目，不是玩具 demo。Instagram 那套 2000 万行的 Python 代码已经默认用 Pyrefly 做类型检查，说明它在极端规模下是稳定的。
编辑体验：不只是“快”，而且“准”
装了 VS Code 扩展（meta.pyrefly）后，你能得到这些功能：
- 跳转到定义、查找引用 —— 比 Mypy 的 stub 导航准得多，因为 Pyrefly 理解运行时类型。
- 自动补全 —— 我在沙盒里试了
request.GET.get('key')，它知道返回值是str | None。 - 悬停信息 —— 鼠标放变量上就显示类型和文档。
- 语义高亮 —— 局部变量、函数参数、类型别名颜色不同，不用装额外的主题插件。
- 内联类型提示（inlay hints）—— 代码里自动显示参数类型，省得你写注解。
Neovim 和 Zed 也有官方支持，其他编辑器去 https://pyrefly.org/en/docs/IDE/ 看具体步骤。
框架支持：Pydantic 和 Django 免配置
多数类型检查器解析 Pydantic 或 Django 时，需要手动装 types-pydantic、django-stubs 等 stub 包，而且经常解析不完备。Pyrefly 直接把这两个框架的模型写进了内核。比如你写：
from pydantic import BaseModel
class User(BaseModel):
name: str
age: int
user = User(name="Alice", age=30)
print(user.name)Pyrefly 不需要任何额外包就能知道 user.name 是 str，user.age 是 int，并且 User(name="Alice") 缺少 age 时会报错。Django 的 QuerySet 链式调用、ForeignKey 关系也能正确推断。这对于重度用这些框架的项目来说，能省掉大量配置 stub 的时间。
迁移三步走：Mypy/Pyright 用户的救星
Meta 自己的代码库从 Mypy 切换到 Pyrefly 的过程中，沉淀出了三个命令，都在文档里写明白了：
-
pyrefly init—— 自动扫描项目中的mypy.ini、pyproject.toml（Pyright 配置）并生成 Pyrefly 的配置文件（pyproject.toml或pyrefly.toml）。你不需要手写任何配置。 -
pyrefly suppress—— Pyrefly 每个月发新版本，可能会因为类型检查更严格而报出新错误。运行这个命令会把当前所有类型错误写到一个忽略列表里，让 CI 保持绿色，你之后再慢慢修。升级时先用suppress过渡，不会阻塞开发。 -
pyrefly infer—— 对没有类型注解的代码自动推断并添加注解。可以只对核心模块运行，逐步扩大范围。
组合用法：先对单个文件启用 Pyrefly → 跑 suppress 把现有错误藏起来 → 用 infer 补上注解 → 之前静默的错误逐渐变少。不需要一天改完所有文件。
版本策略：打破语义化的务实选择
Pyrefly 每个月发一个 minor 版本（1.x.0），紧急修复走 patch。它明确说不遵循严格语义版本控制：minor 版本可能引入更严格的类型检查，导致之前不报错的代码突然报错。但提供了 suppress 命令兜底，让用户自己控制升级风险。这种节奏适合快速迭代，也适合大公司内部统一版本。
适合谁用
- 项目几千行以上，Mypy 检查要等几十秒甚至几分钟 —— Pyrefly 的优势最明显。
- 重度用 Pydantic 或 Django，希望 IDE 自动补全和类型推导能工作，不用额外装 stub 包。
- 正在从 Mypy/Pyright 迁移，需要渐进式方案，不想一次性改完所有文件。
- 小项目（几百行）也值得一试，但速度差距不那么明显。Pyrefly 的沙盒和 pip 安装都很简单，花 5 分钟试试不亏。
上手最快的方式
- 打开沙盒：https://pyrefly.org/sandbox/，零安装，直接写代码看类型检查效果。
- 本地安装：
pip install pyrefly，然后用pyrefly check your_file.py。 - 装编辑器扩展：VS Code 搜
meta.pyrefly；或去 https://pyrefly.org/en/docs/IDE/ 选你的编辑器，每个都有截图和配置步骤。 - 有问题去 Discord（https://discord.gg/Cf7mFQtW7W），Meta 团队的人在里面活跃回复。
Pyrefly 的 license 是 MIT，可以放心商用。
（注意：README 里没有给出具体星星数以外的其他 stars 数据，当前 6174 个 stars 是 GitHub 上的实时数据。）