mypy默认不检查__init__.py和未导入模块，因其按依赖图扫描而非文件系统遍历；若__init__.py未被显式导入或入口未覆盖，即被跳过。
为什么mypy默认不检查__init__.py和未导入模块
mypy默认只对「被显式导入或执行」的文件做类型检查，__init__.py若没被其他模块import、或项目入口未覆盖到某些包路径，就会直接跳过。这不是bug，是设计行为——mypy按依赖图扫描，不是按文件系统遍历。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用
--follow-imports=normal（默认值）时，确保所有待检模块最终能从入口脚本import链抵达 - 想强制全量扫描，改用
--follow-imports=skip+--files显式列出目录，例如：mypy --follow-imports=skip src/ tests/ -
__init__.py里如果只有from .xxx import *且没类型注解，mypy可能推导失败，建议改用显式导入并补__all__
如何让mypy识别typing别名和自定义泛型
mypy对from typing import TypeVar, Generic的支持依赖于正确的声明位置和使用方式。常见错误是把TypeVar定义在函数内部，或泛型类继承时漏掉[T]。
实操建议：
立即学习“Python免费学习笔记（深入）”；
-
TypeVar必须在模块顶层定义，例如：T = TypeVar("T")，不能写在函数里 - 泛型类需继承
Generic[T]，且类名后要带[T]，如：class Stack(Generic[T]): ... - 使用
from __future__ import annotations可延迟求值注解，避免前向引用报错，但要求Python ≥ 3.7 - 自定义类型别名若含泛型参数，要用
ParamSpec或TypeAlias（3.12+），旧版本建议用Union或Any临时绕过
如何配置pyproject.toml让mypy对不同目录启用不同规则
mypy不支持按路径设置多套全局配置，但可通过[tool.mypy.overrides]实现条件化规则——本质是“匹配路径后合并配置”，不是完全独立的子配置。
创建 Flask + Vue.js 全栈项目，采用单端口架构、uv 依赖管理、结构化日志和生产级前端设计。当用户要求以下操作时触发：创建新的 Flask+Vue 项目、搭建 Web 应用、构建全栈 Python+Vue 应用、初始化 Flask Web 项目、设置单端口 Flask 前后端项目。触发词：新建项目、创建项目、搭建项目、Flask项目、Vue项目。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用
[[tool.mypy.overrides]]数组，每个项配module或packages字段，例如：packages = ["tests.*"] - 想对测试代码关闭严格性，加
disallow_untyped_defs = false；对核心模块开启disallow_any_unimported = true - 注意覆盖顺序：越靠前的override优先级越高，且不会继承父配置，缺失项会回退到全局
[tool.mypy] - 路径匹配不支持通配符以外的正则，
src/api/**写法无效，只能用src.api.*
运行时遇到error: Cannot find implementation or library stub for module named "xxx"
这表示mypy找不到该模块的类型信息：要么是纯Python第三方库没提供.pyi存根，要么是本地模块未被正确发现，或是C扩展模块（如numpy）缺少stub包。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 先确认是否已安装对应
types-*包，例如pip install types-requests，但注意types-*仅覆盖部分库，且版本需匹配 - 本地模块报错，检查
pyproject.toml中[[tool.mypy.overrides]]是否误把该路径设为ignore，或exclude正则误伤 - 用
mypy --show-traceback看具体卡在哪行，再结合--verbose确认mypy实际加载了哪些搜索路径 - 临时解决可用
# type: ignore[attr-defined]，但更推荐在pyproject.toml中加[[tool.mypy.overrides]]配ignore_missing_imports = true（仅限确实无法补stub的场景）
全量扫描真正难的不是命令开关，而是让mypy「理解你的模块边界」——它不看你文件夹结构，只认import关系和配置里的packages声明。很多团队卡在CI里扫不出问题，其实是入口脚本太小，或者src/没被声明为package root。
