Python hatch 的环境管理与脚本定义

hatch env create 失败因未识别 python：需用 pyenv/asdf 正确安装并注册，windows 需确保注册表项；脚本需在 hatch.toml 的 [scripts] 下定义；hatch run 自动管理环境并安装项目，hatch env run 仅执行已有环境；prune 不清理自定义路径环境。

hatch env create 创建失败：找不到 Python 版本

hatch 默认不会自动安装 Python，它只调用系统已有的 python 或按 pyenv、asdf 等工具注册的版本。如果你执行 hatch env create py39 报错 No Python interpreter found for specifier 'py39'，大概率是 hatch 根本没看到你装的 Python。

实操建议：

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

• 先运行 hatch env python list，看 hatch 能识别出哪些 Python —— 它不依赖 $PATH，而是查 pyenv 的 versions 目录、asdf 的 shim 路径，或系统 /usr/bin 下的硬链接
• 如果用 pyenv，确保已执行 pyenv install 3.9.18 且 pyenv global 3.9.18（或至少 pyenv local），再试 hatch env create
• Windows 用户注意：hatch 不识别 py -3.9 这类启动器，必须让 pyenv 或官方安装器把 Python 注册进系统“PythonInstallPath”注册表项，否则 hatch 查不到

hatch.toml 中 [scripts] 定义后不生效

脚本定义在 hatch.toml 里，但运行 hatch run lint 提示 Unknown script 'lint'，常见原因是配置位置或格式不对。

实操建议：

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

• [scripts] 必须放在项目根目录的 hatch.toml 中，不能放在 pyproject.toml 里（除非你明确用 [tool.hatch.scripts]）
• 不要写成 [tool.hatch.scripts] 后又在同个文件里写 [scripts] —— hatch 只认其中一种，优先级混乱时直接忽略
• 脚本值支持字符串（如 lint = "ruff check ."）或数组（如 test = ["pytest", "-x", "tests/"]），但不能混用；数组中每个元素必须是纯字符串，不能带 && 或管道符
• 如果脚本依赖未安装的包（比如 ruff），hatch 不会自动装，需提前在对应环境中 pip install ruff，或改用 hatch run --no-project lint 让 hatch 在干净环境里装依赖再跑

hatch env run 与 hatch run 的行为差异

这两个命令看起来都“跑东西”，但触发的环境和隔离程度完全不同：一个针对已有环境，一个针对项目本身。

实操建议：

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

• hatch env run myenv -- pytest：在名为 myenv 的已存在环境中执行 pytest，不检查 pyproject.toml 里的依赖，也不激活项目包（即你的本地代码不会被 import）
• hatch run pytest：先检查 [project.optional-dependencies] 或 [tool.hatch.envs.test.dependencies]，创建/复用一个临时环境，安装项目（editable 模式）、测试依赖，再跑 pytest —— 这才是开发时该用的方式
• 容易踩坑的是：误用 hatch env run 调试脚本，结果发现 import mypackage 报错 —— 因为那个环境压根没装你的项目

hatch env prune 清不掉旧环境

hatch env prune 默认只清理“由 hatch 自动管理”的环境，手动用 hatch env create --python 3.8 myold 创建的环境会被清理，但通过 hatch env create myold（没指定 Python）创建的、或名字含点号/下划线的，可能被跳过。

实操建议：

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

• 运行 hatch env list，确认待删环境名是否出现在列表中 —— 如果没列出来，prune 就不会碰它
• hatch 判断“可清理”的依据是环境路径是否符合其内部命名规则（如 .venv/py39），自定义路径（如 --path /tmp/myenv）永远不被 prune 触及
• 最稳妥的清理方式是直接删目录：rm -rf $(hatch env show --path myold)，再补一句 hatch env remove myold 同步 hatch 内部记录

环境路径生成逻辑藏得深，不同 hatch 版本对“合法环境名”的判断略有出入，别依赖 prune 做自动化清理，手动删更可控。