DEBUG.WIKI
PanstarCloud:部署应用,接入 AI,云服务器与 AI 网关
IPPeak:从目标地区访问网页,住宅代理、SEO 监测、广告验证
ZgoCloud:多地区部署,按需选节点;日本、美国、香港、德国

hatch build 报 No module named hatch:检查隔离环境中的 Hatchling 1.32.1

Hatchling 1.32.1 的后端导入链在隔离环境缺少 hatch。修正实际构建约束,保留隔离和其他插件,并从 sdist 再构建检查产物。

外层已经安装 Hatch,hatch build 仍在构建期间报下面的导入错误:

File ".../hatchling/builders/binary.py", line 7, in <module>
    from hatch.plugin.manager import PluginManager
ModuleNotFoundError: No module named 'hatch'

若隔离构建环境解析到了 Hatchling 1.32.1,这条堆栈对应的是该版本的后端打包问题。Hatch 与 Hatchling 不是同一个发行包:前者负责命令行和环境,后者在隔离环境里承担构建。外层能运行 hatch,不能保证后端环境里也安装了它。

1.32.1 已被撤回,1.32.2 已发布对应修复。1.32.3 随后出现了另一个构建 hook 泛型参数回归,当前可用的 1.32.4 也已修复;它与这里 BinaryBuilder 错误导入 Hatch 的原因不同。选择版本时应同时满足项目与插件的约束。

先确认是不是这一条导入链

检查日志是否依次经过 hatchling/builders/app.py、hatchling/builders/binary.py,然后在导入 hatch.plugin.manager 时失败,并核对实际解析到的 Hatchling 版本。项目源码自己的 import hatch、另一个插件依赖未声明,或仅仅找不到命令行可执行文件,都需要另查。

这次问题可以发生在构建隔离中:构建前端按 pyproject.toml 的 build-system.requires 准备环境,里面通常只安装后端及其声明的依赖。给当前终端再装一次 Hatch,并没有修正有问题的后端发行包。

也不要把关闭构建隔离当成默认办法。它可能因外层刚好装着 Hatch 而掩盖导入失败,却让产物依赖开发机的额外包,下一台机器仍可能失败。

调整后端版本,保留其他构建依赖

对本来采用 Hatchling 的项目,可以把后端固定到经项目确认可用的修复版。以下是仅有该后端依赖时的配置示例:

[build-system]
requires = ["hatchling==1.32.4"]
build-backend = "hatchling.build"

如果原列表还有 VCS 版本插件、元数据插件或自定义 hook,保留那些项,只改 Hatchling 的版本约束。还要查构建专用锁文件、CI 约束与内部包镜像,避免它们继续把版本固定到 1.32.1。撤回发行版不会自动改写已经保存的精确版本要求或内部缓存记录。

修复应落到构建环境实际选择的版本。只把运行环境依赖中的 Hatchling 升级,而 build-system.requires 仍精确指定 1.32.1,下一次隔离构建仍会沿用旧要求。相反,项目本来用的是另一个后端时,不应为了消除同名导入错误直接切换整个构建系统。

验收包括从 sdist 再构建 wheel

保留原配置和之前的构建日志,使用项目既有的干净构建流程,确认新的隔离环境没有选择 1.32.1,原导入链可以通过。随后检查 wheel、sdist 的包名、版本和必要文件,并从生成的 sdist 再构建一次 wheel,避免工作目录中的额外文件掩盖发行包问题。

若构建仍失败,按新的第一处异常继续判断;ModuleNotFoundError 消失后出现文件选择或插件错误,不代表仍是同一故障。回退时恢复经过验证的后端与插件组合、构建锁定记录及产物,不能仅凭恢复了外层 Hatch 的版本就认为环境已还原。