本文讲解在未发布、仅本地使用的 Python 项目中，mypy 报错“Duplicate module named”（如 hello 模块重复）的根本原因及推荐解决方案——通过在 pyproject.toml 中显式排除 build/ 目录，而非依赖 --explicit-package-bases 或 setuptools.py-modules = []。
本文讲解在未发布、仅本地使用的 python 项目中，mypy 报错“duplicate module named”（如 `hello` 模块重复）的根本原因及推荐解决方案——通过在 `pyproject.toml` 中显式排除 `build/` 目录，而非依赖 `--explicit-package-bases` 或 `setuptools.py-modules = []`。
该错误并非源于你的包结构设计缺陷，而是由现代 pip（≥20.1）默认启用的 in-place editable builds（原地可编辑构建）机制引发的副作用：当执行 pip install '.[test]' 或 '.[lint]' 时，pip 会在项目根目录下自动生成 build/ 和 dist/ 目录，并将源码（如 hello/）复制或链接至 build/lib/hello/。此时 mypy 会同时扫描原始路径 ./hello/ 和构建路径 ./build/lib/hello/，从而将同一模块识别为两个来源，触发 Duplicate module named "hello" 错误。
虽然 --explicit-package-bases 可临时绕过此问题（它强制 mypy 仅依据包路径推导模块名，忽略文件系统中的重复副本），但它属于“治标不治本”的命令行补丁，且未在配置文件中持久化；而 setuptools.py-modules = [] 的写法虽能抑制 setuptools 自动发现顶层模块的行为，但本质上是在对抗 pip 构建流程，对纯开发场景而言过度干预、语义不清，且可能在未来版本中失效或引发其他工具链兼容性问题。
✅ 推荐方案：在 pyproject.toml 中明确排除 build/ 目录
这是最直接、最符合工具职责分离原则的做法——mypy 的职责是类型检查，不是构建管理；build/ 是构建产物，理应被静态分析工具忽略：
[tool.mypy]
exclude = [
"venv",
"build", # ← 关键修复：排除构建输出目录
"__pycache__",
".pytest_cache",
]
ignore_errors = false
warn_return_any = true
disallow_untyped_defs = true
? 提示：你还可以一并加入
dist/、.git/等常见非源码目录，提升 mypy 执行效率与准确性。
⚠️ 注意事项：
- 不要依赖
--explicit-package-bases作为长期配置，它无法解决根本冲突，且在 CI 中需额外传递参数，增加维护成本； - 避免滥用
setuptools.py-modules = []：该配置本意是声明纯模块（.py文件而非包），与你拥有hello/__init__.py的包结构相悖，易误导其他工具（如 IDE 或打包脚本）； - 若使用 GitHub Actions 等 CI 环境，请确保每次运行前清理构建残留（例如添加
rm -rf build/ dist/步骤），或在pyproject.toml中统一管控exclude列表，实现本地与 CI 行为一致。
总结：对于不发布、仅本地开发测试的 Python 项目，将 build/ 显式加入 mypy 的 exclude 列表是最简洁、可靠、符合工具设计意图的解决方案。它直击问题根源，无需修改构建逻辑，也无需引入语义模糊的配置项，是兼顾正确性、可维护性与可移植性的最佳实践。
