Pyrefly：Meta开源的Python静态类型检查利器

为什么Python代码总在运行时才崩溃

写过Python的人都遇到过这种情况：一段代码看起来毫无问题，编辑器里没有红色波浪线，程序甚至能正常运行到某一行，然后突然崩溃。这类bug的根源在于Python是动态类型语言——变量的类型在运行时才确定，而且可以在程序执行过程中随时改变。

这种设计让Python写起来更快、更灵活，对初学者也更友好，因为你不必操心复杂的类型声明。但代价是：大量类型错误只有在真正执行代码时才会暴露，有时甚至会一路溜进生产环境，造成严重问题。

视频中展示了一个典型例子：一个购物车结算脚本，cart里混入了字符串值（本应全是浮点数）。当代码执行到用字符串乘以浮点数这一步时，就抛出了 TypeError: can't multiply sequence by non-int of type float。另一个bug则是因为折扣函数在传入非法参数时返回了 None，导致 1 - None 的报错。这些都是运行前完全看不到、必须靠反复执行才能发现的隐患。

类型提示（Type Hints）为什么还不够

很多人会说：那加上类型提示（type hints）不就行了？确实，在生产级代码库里你经常会看到带类型注解的函数——参数标注为 str、int、float、bool，返回值标注为 list、dict、自定义数据类等等。这些注解能为编辑器提供自动补全，帮助开发者写出更规范的代码。

但问题在于：Python的内置类型提示本身不做强制检查。视频中演示了一个所有类型都写错的函数——参数、返回值统统标注错误，然而运行起来毫无障碍，Python根本不在乎。换句话说，光写类型提示并不能保证在运行前捕获错误。

要真正发挥类型提示的价值，你需要的是静态类型检查器（static type checker）。

静态类型检查器到底做什么

静态类型检查器是一个在不运行代码的前提下阅读你代码的程序。它会追踪程序中每一个值的流向，对照你写的类型提示，标记出所有类型对不上的地方。

如果你写过C++、Java或Rust，这正是编译器在构建程序前自动帮你做的事。但Python因为是动态类型，根本没有这个编译步骤，所以类型检查需要作为一个独立工具单独安装使用。

多年来，Python生态里的默认选择一直是 MyPy。它能用，但有两个硬伤：

• 慢：在大型代码库上，一次类型检查可能要几分钟。
• 编辑器与CI不一致：你在编辑器里跑的检查器往往和CI流水线里跑的是不同工具，结果就是编辑器说没问题、流水线却报出你从没见过的错误。

静态类型检查器的核心技术是数据流分析（data flow analysis）和类型推断（type inference）。它不仅逐行验证类型声明，还会追踪变量在整个程序生命周期内的赋值和传递路径。例如，当一个函数的返回值被传入另一个函数时，检查器能推断出中间变量的类型，即使该变量没有显式注解。现代类型检查器还支持类型收窄（type narrowing）：当代码中出现 if x is not None 这类条件判断时，检查器能理解在该分支内 x 已排除了 None 类型。Python生态中常见的静态类型检查器除了MyPy和Pyrefly，还有微软开发的Pyright（VS Code内置Pylance的底层引擎）以及Google的pytype，各工具在性能、规则严格程度和对第三方库存根文件的支持上各有侧重。

Meta为什么重写了Pyrefly

Meta在远超常人规模的场景下同时撞上了这两个问题。以Instagram为例——这是全球最大的Python代码库之一，拥有数千万行Python代码。用现有工具检查这个代码库太慢，根本无法在每次改动时都跑；工程师还经常在编辑器里看到一组错误、在CI里看到另一组错误。

于是Meta把一个原本用OCaml写的旧类型检查器Pyre用Rust重写，速度大幅提升，并直接部署到Instagram的真实代码库上。这个工具就是 Pyrefly。

它最关键的特性是：编辑器、终端、CI用的是同一个引擎，所以三者永远不会相互矛盾。它免费、开源、极快，VS Code扩展的下载量已经达到约8100万次。目前Instagram和PyTorch都在使用它。

如何安装与使用Pyrefly

安装方式有几种。如果用包管理器UV，一行 uv add pyrefly 就能加进项目；也可以直接 pip install pyrefly。如果你在VS Code或其分支（如Cursor）里，直接搜索Pyrefly扩展安装即可。建议两者都装，这样既有IDE内的即时提示，也能从终端运行。

装好后打开那个有bug的脚本，IDE扩展会立刻高亮所有类型不匹配的地方，并提示具体的类型冲突，让你在运行代码前就能修复。它还能为函数推断类型，双击就能自动插入。

当你把 price 标为 float、把 cart 标为 list[dict[str, float]] 之后，之前那个坏购物车的错误会被立即点出：参数类型不可赋值给对应形参。你也不必只在编辑器里看——运行 uv run pyrefly check 会扫描整个项目并列出所有错误，可以用在CI、Git pre-commit钩子，或手动执行。

从MyPy迁移

如果你项目里已经有 mypy.ini，Pyrefly提供一条命令就能自动迁移——它会检测到已有配置，生成一份等价的 pyrefly.toml。迁移时它还会询问是否要抑制当前已存在的错误，这样你可以只对新代码启用检查、暂时忽略历史遗留问题。

需要注意的是：如果项目里没有任何配置文件，Pyrefly会以basic模式运行，只检查最严重的类型问题。想要更激进的检查，就需要添加配置文件。所以初次使用时，务必先生成一份配置。

类型提示仍是前提

一个重要提醒：静态检查器要发挥作用，你仍然需要给代码加类型。视频演示中有个带类型不匹配的脚本，但因为完全没写类型注解，Pyrefly跑出来显示“0 errors”。只有当参数、返回值都标注清楚后，比如把 user: User | None 传给期望 User 的函数时，它才会报错。想修复，就得用 if user is not None 做类型收窄（narrowing），之后检查器会确认类型已安全。

**类型收窄（type narrowing）**是静态检查器理解条件逻辑的关键机制。当变量类型被声明为联合类型（如 User | None）时，检查器在进入 if user is not None: 分支后，会自动将该变量的类型缩小为 User，从而允许后续代码访问 User 的属性而不报错。除了 is not None 检查，常见的收窄方式还包括 isinstance() 判断、assert 语句，以及对字面量类型的等值比较。这一机制让类型系统能够精确描述"函数有时返回有效值、有时返回空"这类现实场景，而无需把所有调用方都改写成处理最宽泛类型的代码。

速度实测：Pyrefly vs MyPy

视频用NumPy、PyTorch、scikit-learn三个流行库做了对比测试：

• scikit-learn：MyPy用了约6.3秒，Pyrefly几乎瞬间完成（约1秒），快约6倍。
• PyTorch：MyPy耗时54.92秒，Pyrefly只用3.7秒（输出了约2.1万个错误），快约15倍，而且大部分时间还花在把结果打印到终端上。
• NumPy：MyPy用了1分49秒，Pyrefly仅20秒（约2.86万个错误）。

差距随代码库规模扩大而急剧拉开，这正是Meta在超大规模场景下最看重的改进。

让AI Agent也用上Pyrefly

如果你用AI agent写Python代码，可以把Pyrefly加进agent的工作循环。官方文档给出了做法：添加一个CLI skill，再配一个 agents.md 文件，指示模型每次改动后都运行检查。实际操作中，只需把官方文档页面链接丢给模型，让它“添加Pyrefly agent skill并在agents.md里要求每次改动都用这个skill”，它就会自动生成 skill.md 和 agents.md。

如果这种方式不奏效，也可以用CLI hooks——在Claude Code、Cursor等工具里写自定义钩子，让它在特定改动后自动运行检查。

总结

对于编写生产级Python代码的开发者，Pyrefly几乎没有不用的理由：免费、开源、与MyPy相比快出数倍到数十倍，而且IDE、终端、CI三端引擎统一，不会出现结果打架的情况。配合规范的类型注解，它能在代码运行前就拦下大量隐藏的类型bug，显著提升代码的可维护性。安装只需 pip install pyrefly 或装一个编辑器扩展即可。