如何设置VSCode以启用MyPy进行Python代码的严格类型验证？

本文共计825个文字，预计阅读时间需要4分钟。

在VSCode中启用MyPy进行代码风格检查，无需安装mypy，只需配置即可自动生效。具体步骤如下：

确认 mypy 已安装且路径正确

VSCode 不会自己找 mypy，必须明确告诉它可执行文件在哪。终端运行 which mypy（macOS/Linux）或 where mypy（Windows），有输出才说明装好了。没输出就先 pip install mypy。

• 如果用虚拟环境，路径通常是 ./venv/bin/mypy（Linux/macOS）或 ./venv/Scripts/mypy.exe（Windows）
• 在 VSCode 设置里搜 “mypy path”，填进这个绝对路径；别依赖默认查找，多环境时极易错用系统 Python 的 mypy
• 路径里含空格或中文？换到纯英文路径下重装 mypy，避免解析失败

在 settings.json 中启用并传参

python.linting.mypyArgs 必须是数组格式，每个参数单独一项，字符串拼接会静默失效。

• 启用严格模式：加 "--strict"，它等价于一堆独立开关（disallow_untyped_defs、disallow_incomplete_defs 等）
• 指定 Python 解释器：加 "--python-executable" 和对应路径，否则 mypy 可能找不到你项目里装的包或 stubs
• 别加 --file 或 --follow-imports：VSCode 自己控制检查范围，硬加反而干扰
• 示例有效写法：

  "python.linting.mypyArgs": ["--strict", "--python-executable", "./venv/bin/python"]

关掉 Pylance 的类型检查干扰

Pylance 默认开着，它也会标红类型问题，但它的“严格”和 mypy 的 --strict 完全不是一回事——Pylance 不报 reportMissingTypeStubs，也不强制函数注解，容易让你误以为“没错误”。

立即学习“Python免费学习笔记（深入）”；

• 打开设置，搜 python.languageServer，把它从 Pylance 改成 None 或干脆卸载 Pylance 插件（只留官方 Python 扩展）
• 或者至少把 python.analysis.typeCheckingMode 设为 "off"，避免双语言服务器打架
• 改完重启窗口，右下角状态栏要看到 “mypy” 字样，而不是 “Pylance” 或 “Default”

注意 pyproject.toml 的优先级

如果你项目根目录有 pyproject.toml，mypy 会优先读里面的 [tool.mypy] 配置，settings.json 里的 mypyArgs 只是补充。

• 检查 pyproject.toml 是否有 [[tool.mypy.overrides]] 把你当前文件路径 exclude 了
• Windows 下路径正则要转义：比如 "--exclude", "tests\.*"（四个反斜杠），写成 "tests.*" 会直接失效
• mypy ≥ 1.0 默认输出 JSON，老版 VSCode Python 扩展解析不了——升级插件到 v2023.10+ 以上

最常被忽略的一点：VSCode 默认只 lint 当前打开的文件，跨文件类型错误（比如 A.py 调用 B.py 里未注解的函数）不会触发，除非 B.py 也被打开过一次。真要全量检查，还是得靠终端跑 mypy .。