EPGF 新手教程 13在 PyCharm（中文版 GUI）中创建 Hatch 项目环境，并把 Hatch 做成“项目自包含”（工具本地化为必做环节）

【EPGF 白皮书】路径治理驱动的多版本 Python 架构------ Windows 环境治理与 AI 教学开发体系

EPGF 新手教程 13

在 PyCharm（中文版 GUI）中创建 Hatch 项目环境，并把 Hatch 做成"项目自包含"（工具本地化为必做环节）

副标题：Hatch 是现代项目管理与环境工具，但默认创建并不代表可迁移------EPGF 要求把工具"请进".venv

一、结论先行（给读者定心）

Hatch 在 PyCharm 中被官方支持：创建项目时可以选择 Hatch 环境类型，IDE 会生成 pyproject.toml 并协助创建/识别 Hatch 项目（官方说明）。但Hatch 的默认创建流程并不能保证 hatch.exe 被放入项目的 .venv\Scripts 。在 EPGF 架构下，务必在 PyCharm 自动激活的项目终端里执行工具本地化（pip install hatch 或等效步骤），把 hatch.exe 放到 .venv\Scripts，才能让项目具备真正的"可迁移/可复现"能力。(JetBrains)

二、前置回顾（与 EPGF 已完成的一致行为）

在前面篇章你已经完成了 EPGF 的治理基础：

Anaconda 安装在 D:\A，并建立了版本层（例如 D:\A\envs\py311）。
在父级 Python（版本层）中统一安装过常用管理工具（示例路径）：
复制代码
```
D:\A\envs\py311\python.exe
D:\A\envs\py311\Scripts\hatch.exe
```

这些是 EPGF 的统一来源层 （便于版本治理），但不是项目的自包含层。创建项目后，还必须把工具"请进项目"。（与 uv / poetry 完全同构）

三、官方要点（PyCharm 对 Hatch 的支持，摘录要点）

PyCharm 支持 Hatch：在创建新项目时可选择 Hatch，IDE 会自动生成 pyproject.toml。(JetBrains)
PyCharm 会尝试自动检测 已安装的 Hatch；如果未检测到，可以手动指定 Hatch 可执行文件 或让 IDE 在所选解释器上安装相应工具。(JetBrains)

（以上详见 PyCharm 官方文档 Configure a Hatch environment。）(JetBrains)

四、EPGF 下的 GUI 流程（中文 PyCharm，逐步操作）

目标：用 PyCharm GUI 创建 Hatch 项目环境，并把 Hatch 工具本地化到项目 .venv（无须命令行基础的读者也能完成）

步骤 1 --- 新建项目

PyCharm → 文件 → 新建项目。

步骤 2 --- 选择环境类型为 Hatch（非常关键）

在右侧的环境配置区：

环境类型 ：选择 Hatch（不要选 venv/Conda/System）。
Python 解释器来源 ：选择 已有解释器，指向父级解释器，例如：

D:\A\envs\py311\python.exe

说明：Hatch 环境必须"寄生"在某个父级 Python 上（EPGF 的版本层），父级负责统一来源与治理。(JetBrains)

步骤 3 --- 指定父级 `hatch.exe`（若 PyCharm 未自动检测）

PyCharm 会尝试检测 Hatch；若未检测到，请手动浏览并指定父级工具路径，例如：

复制代码

D:\A\envs\py311\Scripts\hatch.exe

这一步只是把"父级工具"指向 PyCharm，便于 IDE 用它来创建或识别 Hatch 环境（注意：此刻该 exe 仍属于父级，不是项目自带）。(JetBrains)

步骤 4 --- 保持环境位置为 `<项目目录>\env`（EPGF 标准）并点击【创建】

PyCharm 会在项目目录下生成 pyproject.toml 并创建或绑定项目虚拟环境（或让 Hatch 在项目内创建环境，取决于你的选择与 Hatch 配置）。(JetBrains)

五、创建后检查：为何"半成品"常见？

创建完项目后，查看项目内的虚拟环境（以默认 env\virtual\hatch\Scripts 为例）通常会看到：

复制代码

env/virtual/hatch/Scripts
├─ python.exe
├─ pip.exe
└─ （可能没有 hatch.exe）

这是常见且正常的情况：即使你用父级 Hatch 创建了环境，env 并不一定包含 hatch.exe （Hatch 本身多数时候作为外部工具存在于父级路径），因此项目仍处"半成品"状态。(JetBrains)

六、EPGF 的必做步骤：在 PyCharm 终端执行工具本地化（强制要求）

步骤 5 --- 打开 PyCharm 内置终端（自动激活 `.venv`）

点击 PyCharm 底部 终端（Terminal），确认提示行前显示：

复制代码

(hatch) PS D:\Projects\demo_hatch_project>

这表示 PyCharm 已自动激活项目虚拟环境（或 Hatch 在项目内的 env 已被激活）。(JetBrains)

步骤 6 --- 在已激活的 `.venv` 中执行本地化安装

在该终端中运行（在项目 .venv 环境内）：

复制代码

pip install hatch

（或者使用 Hatch 官方推荐的方式在项目虚拟环境内安装 Hatch，使其可执行文件进入 env/virtual/hatch/Scripts。）

步骤 7 --- 验证 `env/virtual/hatch/Scripts/hatch.exe` 出现

安装完成后，检查项目结构，你应看到：

复制代码

env/virtual/hatch/Scripts/hatch.exe

此时项目真正达成工具本地化 ：Hatch 工具随项目 env 一起移动，项目成为自包含单元。

注：

以上仅为示例！

最新的创建环境和管理环境的方式，请关注 hatch 官方文档！

uv\poetry\hatch 等这些现代的环境管理工具，仍在高速迭代中，创建和管理环境的方式会随着工具的发展而有所差异，但不管何种迭代差异，仍不影响在 EPGF 架构下能良好的使用这些工具。
pypa/hatch：现代且可扩展的Python项目管理
 环境配置 - Hatch
Anaconda 全环境工具链路径树管理和环境创建指南（Poetry、Pipenv、venv、uv、Hatch）
【笔记】PyCharm 2025.2 EAP 创建 Poetry 和 Hatch 环境的踩坑实录与反馈
 命令行创建项目本地的 hatch 环境及工具本地化实战演示------基于《Python 多版本与开发环境治理架构设计》的最佳实践
 【深度探索】Windows 下 Python 多版本虚拟环境管理与隔离实战：支持 Anaconda、Poetry、Pipenv、venv、uv、Hatch、PyCharm、VS Code 全工具链方案
 【零基础】Python 多版本虚拟环境管理与隔离实战------支持 Anaconda、Poetry、Pipenv、venv、uv、Hatch、PyCharm、VS Code 的统一工具链方案
 【终极实战】Conda/Poetry/Virtualenv/Pipenv/Hatch 多工具协同 + Anaconda×PyCharm：构建 Python 全版本栈隔离体系与虚拟环境自动化管理指南

七、理论高潮（与 11 / 12 篇同构的核心判定段）

现代项目管理工具（Hatch / Poetry / uv）与传统 virtualenv + pip 的根本差别在于：锁文件或 pyproject.toml 提供版本/依赖的确定性 ，但这些文件本身不是执行器 ；它们需要相应的工具来解析并执行。若项目迁移后 .venv 中并没有 hatch.exe（或对应的工具），即使锁文件存在，项目也无法运行 hatch 命令来恢复或管理依赖，因此不具备"自我管理依赖状态"的能力，也就失去了工程所需的迁移复现能力。

EPGF 的判定标准非常直接：

激活项目环境后，项目是否能独立执行依赖管理命令 ？

不能 → 尚未完成治理（必须本地化工具）。

这一判断适用于所有现代工具，Hatch 也不例外。（参见 PyCharm 官方关于 Hatch 环境的说明）。(JetBrains)

八、示例（最终工程结构示意）

复制代码

D:\Projects\demo_hatch_project\
├─ env\virtual\hatch\
│  ├─ Scripts\
│  │  ├─ python.exe
│  │  ├─ pip.exe
│  │  └─ hatch.exe    ← 已本地化，项目自包含
├─ pyproject.toml
├─ hatch.lock (或其他 hatch 生成的锁文件)
└─ src\

九、实践建议（EPGF 风格速查）

父级先统一安装 Hatch （治理层）并记录路径：
D:\A\envs\py311\Scripts\hatch.exe（便于 PyCharm 指定）。
PyCharm 新建时指定父级 Python ：让环境基于明确版本创建。(JetBrains)
创建后务必在 PyCharm 终端本地化安装 Hatch （pip install hatch 或等效配置），把 hatch.exe 带进 env。
把 pyproject.toml 与 Hatch 的锁文件纳入版本控制，但别把迁移希望寄托在锁文件上------工具本地化才是执行保障。

参考（已核验）

PyCharm 官方：Configure a Hatch environment（关于在 PyCharm 中配置 Hatch 环境的官方说明）。(JetBrains)

EPGF 新手教程 13在 PyCharm（中文版 GUI）中创建 Hatch 项目环境，并把 Hatch 做成“项目自包含”（工具本地化为必做环节）