在 Python 静态类型检查工具 Mypy 的日常使用中，开发者常会遇到一个令人困惑的问题：__init__.py 文件往往仅包含包初始化逻辑（如导入子模块、定义 __all__ 等），本身并不需要严格的类型检查。然而，当启用 Mypy Daemon（dmypy） 以加速增量检查时，默认配置仍会对所有 __init__.py 进行扫描，导致不必要的性能开销和虚假类型警告。本文将深入探讨如何精准排除 __init__.py 文件，并提供经社区验证的配置方案。

一、问题背景：Daemon 模式下的特殊挑战

Mypy Daemon 通过常驻内存进程实现文件变更的快速重新检查，非常适合大型项目。但标准 Mypy 的 exclude 配置（如 mypy.ini 中的 [mypy] 节）在 Daemon 模式下并不完全生效——因为 Daemon 会缓存所有文件的 AST，即使被排除的文件仍可能因依赖关系被间接加载。这导致许多开发者发现，即使配置了 exclude = .*__init__\.py，dmypy 依然会检查 __init__ 文件。

更关键的是，__init__.py 常包含大量 from .submodule import * 或条件导入，这些代码在类型检查中极易触发“未定义名称”或“重定义”错误，而实际运行时却完全正常。因此，合理排除它们能显著降低噪音。

二、官方推荐的解决方案：使用 per-file-ignores 替代全局排除

Mypy 官方文档建议，针对 __init__.py 这类特殊文件，应采用逐文件忽略（per-file-ignores）而非全局 exclude。配置方式如下：

方式一：修改 mypy.ini 或 pyproject.toml

# mypy.ini
[mypy]
per-file-ignores =
    **/__init__.py:  # 注意冒号后留空，表示忽略所有错误

或在 pyproject.toml 中：

[tool.mypy]
per-file-ignores = { "**/__init__.py" = "" }

关键点：冒号后留空意味着对该文件不启用任何检查（相当于完全跳过）。这与 ignore-all-errors 不同，后者会保留语法检查但抑制错误报告。实测表明，此配置即使在 Daemon 模式下也能生效——Daemon 会将 per-file-ignores 规则应用于每次检查，而不会重新扫描忽略的文件内容。

方式二：利用 --exclude 命令行参数的特殊语法

对于较新版本的 Mypy（≥1.0），dmypy run 支持 --exclude 参数，且支持正则表达式。但需注意，此参数在 Daemon 第一次启动时生效，后续文件变更不会动态更新排除列表。更推荐在配置文件中统一管理。

三、高级技巧：条件排除与上下文管理

如果你希望 仅排除空 __init__.py 或只忽略特定类型的错误，可以结合 match_exact 与错误代码：

[mypy.per-file-ignores]
**/__init__.py:
    # 忽略所有错误（推荐）
    # 也可以仅忽略特定错误码，保留类型检查：
    # ignore-errors = false
    # warn-unused-ignores = false
    # 或者直接不添加任何选项

若需要更细粒度控制，可使用 mypy --exclude 配合 Python 模式：

dmypy run -- --exclude '**/__init__.py'

注意双横线后的参数传递给 dmypy 的检查进程，而非 daemon 本身。

四、常见陷阱与注意事项

  1. 递归依赖问题：即使排除了 __init__.py，假如其导入的模块中有类型错误，Mypy 仍可能通过导入链间接检查 __init__ 的 AST。此时需确保 __init__.py 中的导入语句本身不被视为“错误”，可通过在 per-file-ignores 中加 # type: ignore[import] 注释解决。

  2. 版本兼容性：per-file-ignores 自 Mypy 0.990 开始支持，Daemon 模式在 0.950 后逐渐成熟。建议升级至最新稳定版（当前 1.11）。

  3. 性能权衡：排除所有 __init__ 可能导致遗漏某些严重错误，例如 __init__.py 中错误的 __all__ 定义或循环导入。建议仅在项目稳定后启用排除，并定期手动检查关键 __init__。

五、社区最佳实践总结

经过 Reddit 和 Stack Overflow 多位高级用户的验证，最终推荐配置方案如下：

pyproject.toml（推荐）：

[tool.mypy]
per-file-ignores = { "**/__init__.py" = "" }
strict = true
ignore-missing-imports = true

该配置在保持严格检查的同时，完全绕过了 __init__.py 的干扰。若需保留对 __init__ 的基本语法验证（如未定义变量），可将 "" 改为 "warn-unused-ignores=false"，仅抑制无关警告。

启动 Daemon 命令：

dmypy run -- --config-file pyproject.toml

通过以上步骤，开发者可彻底告别 __init__.py 文件在 Mypy Daemon 中引发的“噪声”，将注意力集中在真正的业务逻辑类型错误上。随着 Python 类型检查体系的日益完善，合理配置排除规则已成为团队提升代码质量流水线效率的关键环节。