Pyrefly：高性能的 Python 类型检查器
内容提要
本文介绍如何用 pyrefly 为 CI 配置 Python 类型检查。2026 年可选工具包括 mypy、pyright、pyrefly、ty、zuban，其中 pyrefly 和 ty 有公司支持且速度快，适合新项目。配置只需在 pyproject.toml 中设置包含、排除路径等。文章还讲解修复常见类型错误的方法，如 None 属性、返回类型不兼容、TypedDict 缺失字段、无匹配重载，并评价 pyrefly 快速全面但报错有时难懂。
延伸解读
2026 年类型检查器选型参考
文章指出，2026 年可选工具包括 mypy、pyright、pyrefly、ty 和 zuban。其中 pyrefly 和 ty 由公司支持且速度快，适合新项目；zuban 为个人项目且采用 A-GPL 许可证，商业使用需注意。作者建议新项目在 pyrefly 和 ty 之间选择，并提供了类型规范符合性测试链接供参考。
pyrefly 配置与错误抑制
pyrefly 配置简单，在 pyproject.toml 中设置 project-includes、project-excludes、search-path 和 output-format 即可。文章给出了示例配置，并提到可通过官方文档了解错误抑制方法。这降低了在 CI 中集成类型检查的门槛。
常见类型错误修复模式
文章列举了四类常见错误：None 属性访问、返回类型不兼容、TypedDict 缺失字段和无匹配重载。修复方法包括类型收窄、使用 @overload 装饰器、利用 total=False 与 Required/NotRequired 组合，以及显式注解为 dict[str, Any]。这些模式有助于快速解决类型检查问题。
pyrefly 的局限与注意事项
作者认为 pyrefly 快速全面，能帮助捕获潜在 bug，但有时错误信息难以理解。此外，pyrefly 仍在积极开发中，可能遇到性能问题，例如曾出现检查代码片段耗时超过 1000 秒的情况，不过团队已快速修复。使用时需关注其发展动态。
Q&A
2026年有哪些Python类型检查器可选？各自有什么特点？
2026年可选的Python类型检查器包括mypy、pyright、pyrefly、ty和zuban。其中pyright和mypy速度较慢；pyrefly、ty和zuban用Rust实现，速度很快。pyrefly和ty由公司维护，更可能长期支持；zuban是个人项目，且采用AGPL许可，商业使用需获得商业许可。新项目建议选择pyrefly或ty。
如何为pyrefly配置pyproject.toml？
在pyproject.toml中添加[tool.pyrefly]部分，可设置project-includes（包含路径）、project-excludes（排除路径）、search-path（搜索路径）和output-format（输出格式）等。示例：project-includes = ["app"]，project-excludes = ["**/tests"]，search-path = ["app"]，output-format = "min-text"。
pyrefly报错“None type does not have attribute 'get'”该如何修复？
这是因为变量类型为dict | None，直接调用.get()会报错。可以通过类型收窄修复：先检查是否为None，例如if my_val is None: raise RuntimeError(...)，或if my_val is not None: my_val.get("key1")。
函数根据参数返回不同类型时，pyrefly报错“set does not have attribute 'get'”怎么办？
可以使用@overload定义重载，根据参数字面量类型指定返回类型。例如用Literal[True]和Literal[False]分别重载，返回set或dict。另一种方法是将函数逻辑拆分到不同函数中，可能更好。
使用TypedDict时，如何允许初始化空字典并标记必需字段？
定义TypedDict时设置total=False，这样所有字段默认可选，可以初始化空字典。然后使用Required标记必需字段，NotRequired标记可选字段。例如：class Config(TypedDict, total=False): host: str; port: int; debug: Required[bool]。
pyrefly报错“no matching overload”是什么原因？如何解决？
这是因为pyrefly对字典值类型推断过于急切。例如初始化params为dict[str, int | str]后，再update一个值为list的字典，会因类型不匹配报错。解决方法是将params显式注解为dict[str, Any]，这样pyrefly就不会报错。
pyrefly的整体使用体验如何？有哪些优缺点？
pyrefly是一个快速且全面的类型检查器，能帮助捕获潜在bug。但有时错误信息难以理解，且仍处于活跃开发中，可能存在性能问题（如曾出现检查代码片段耗时超过1000秒，但已快速修复）。
