3 分钟装好 mypy：新手静态类型检查完整配置指南

3 分钟装好 mypy：新手静态类型检查完整配置指南

【免费下载链接】mypyOptional static typing for Python项目地址: https://gitcode.com/GitHub_Trending/my/mypy

mypy 是 Python 的静态类型检查器——不运行代码，靠类型标注在运行前揪出类型写错的地方。这篇文章带你完成安装、第一次运行、日常配置和避坑，读完就能在自己的项目里跑类型检查。

类型错误，非得等运行时才知道吗

Python 是动态语言，把 123 传给只接受字符串的参数，当下不报错，要等执行到那一行才崩。mypy 做的是静态分析：还没运行，它就能告诉你greet(3)这种调用里"int 传给了期望 str 的参数"。

另外 mypy 支持渐进式类型标注——没有标注的函数默认不检查，你可以只给新代码加标注。老项目引入时不用一次重写全部代码。

一条命令安装 mypy

先确认你的 Python 是 3.10 或更高（mypy 需要 3.10+ 才能运行 ⚡），然后用 pip 安装：

python3 -m pip install mypy

这一步装上 mypy 命令行工具，同时会带入 typeshed 数据库，它提供标准库的类型信息。如果想用最新源码，clone 仓库（git clone https://gitcode.com/GitHub_Trending/my/mypy）后执行python3 -m pip install .即可。

验证安装是否成功

建一个临时文件example.py：在里面写一个带参数和返回值标注的函数（比如定义def greet(name: str) -> str，返回'Hello ' + name），然后故意传一个错的参数调用它：greet(3)。

接着运行：

mypy example.py

输出里出现error: Argument 1 to "greet" has incompatible type "int"; expected "str"就说明装好了 ✅——这个错误要等运行时才暴露，mypy 现在直接拦住了。

注意：mypy 报错时，代码照样能用 python3 跑起来。类型标注类似注释，不影响运行。

日常配置怎么弄

常用选项可以写进配置文件，mypy 会从当前目录向上逐级自动查找。它支持mypy.ini、.mypy.ini、pyproject.toml的[tool.mypy]段和setup.cfg的[mypy]段，任选其一放在项目根目录就行。

两个高频选项值得先记住：

• strict = True：一次开启一组额外检查，建议先在小项目试 🧪
• ignore_missing_imports = True：让 mypy 别为缺少类型标注的第三方库报"找不到类型信息"。更稳的写法是按模块配置，比如单独设一个[mypy-somelibrary]段，只屏蔽那一个库。

其余高级选项，见 docs/source/command_line.rst。

避坑指南

"Library stubs not installed" 报错：常用的第三方库没有自带类型标注时会出现，报错信息里会直接给出提示，按提示装对应 stub 包即可，例如python3 -m pip install types-PyYAML。

明显写错却没报错：多半是出错的函数没有任何标注，mypy 默认不检查它。给参数和返回值补上标注，或用--check-untyped-defs让它连这类函数也检查。

类属性悄悄变成 Any：__init__没写标注时，实例变量的类型会退化成 Any，错误就不再暴露。给__init__补上-> None并标注字段即可。

装不上：先查 Python 版本，低于 3.10 就升级 Python 或换一个更新的解释器。

接下来看哪里

建议先过一遍类型标注速查表掌握最常用写法，再读入门指南深入理解；完整配置参数参考配置文件章节，遇到问题查常见问题解答。

【免费下载链接】mypyOptional static typing for Python项目地址: https://gitcode.com/GitHub_Trending/my/mypy