命令行创建项目本地的 hatch 环境及工具本地化实战演示——基于《Python 多版本与开发环境治理架构设计》的最佳实践

原创于 2025-07-31 01:10:58 发布 · 1.1k 阅读

22 ·

CC 4.0 BY-SA版权

文章标签：

#python #开发语言 #windows #人工智能 #架构 #hatch

运维同时被 3 个专栏收录

87 篇文章

订阅专栏

Anaconda

53 篇文章

订阅专栏

PyCharm

41 篇文章

订阅专栏

Python 多版本环境治理理念驱动的系统架构设计：三维治理、四级隔离、五项自治原则-CSDN博客

命令行创建 UV 环境及本地化实战演示—— 基于《Python 多版本与开发环境治理架构设计》的最佳实践-CSDN博客

一、工具链路径树状图示例

以 D:\Conda\envs\py312\ 为虚拟环境路径示例，我们已在该环境中集成多种构建工具，包括 hatch、poetry、pipenv、uv 等。

统一安装的环境管理工具链：

【笔记】为什么不推荐交叉混用 pip install 与 conda install，却建议在 conda 环境中用 pip 安装环境管理工具？-CSDN博客

pip install poetry virtualenv pipenv uv hatch pipx nox tox

D:\Conda\envs\py312\  
├─ python.exe                  # 基础 Python 解释器  
├─ Scripts\                    # 工具目录  
│  ├─ poetry.exe               # 包管理工具（Poetry 示例）  
│  ├─ virtualenv.exe           
│  ├─ pipenv.exe                # 多方案共存  
│  ├─ uv.exe                    
│  └─ hatch.exe                # hatch 工具链（待本地化）  
└─ Terminal 命令（py312 环境中执行）：  
   hatch env create            # 创建 hatch 虚拟环境（默认在 C 盘）  
   hatch shell                 # 激活 hatch 虚拟环境

说明：

基础环境（py312）是 Hatch 工具本身的运行环境，需先通过conda activate py312激活。
Scripts目录存放所有可直接调用的工具命令，确保该目录已添加至系统环境变量（PATH），否则需通过绝对路径调用hatch.exe。

☑️ 本文目标：实现 hatch 虚拟环境的 项目本地化 创建，摆脱默认的 C:\Users\路径限制，融入路径治理体系。

二、Hatch 环境特性详解

Hatch 是 Python 官方推荐的现代项目管理工具，集成了虚拟环境管理、依赖管理、打包发布等功能，其核心特性包括：

环境隔离性：通过创建独立虚拟环境，避免不同项目的依赖冲突（与virtualenv、poetry一致）。
多环境支持：可在同一项目中创建多个环境（如dev开发环境、test测试环境），并为每个环境配置不同依赖。
配置自动化：通过项目根目录的pyproject.toml文件统一管理项目元信息、依赖及环境配置，符合 PEP 标准。

然而，Hatch 的默认行为存在一个不符合 “本地化治理” 的问题：

默认环境路径问题：Hatch 会将虚拟环境默认创建在系统用户目录（如C:\Users\<用户名>\AppData\Local\hatch\envs），而非项目根目录内。
这会导致环境与项目分离，不利于项目迁移和长效管理（如复制项目到其他设备时或 IDE 缓存失效找不到原先环境，从而需重新创建并管理环境），且可能占用系统盘（C 盘）空间。

因此，我们需要通过配置调整，让 Hatch 将虚拟环境创建在项目本地目录（如项目根目录下的env文件夹），实现 “环境随项目走” 的本地化治理目标。

三、Hatch 虚拟环境默认行为说明

官方文档：Basic Environment Usage - Hatch

Managing environments - Hatch

hatch 的默认行为是在 用户目录（C:\Users\<UserName>\.local\...） 中创建项目虚拟环境。这种策略虽然适合快速开发，但在以下场景中会带来问题：

无法统一纳入路径治理结构；
无法进行便携式迁移或复制；
不适用于教学分发或多用户共享；
环境隔离不够直观（本地无 env 目录）；

因此，我们探索出一种 通过 config.toml 配置文件 + 本地命令激活 的方式，实现项目虚拟环境的完全本地化。

四、Hatch 配置文件 config.toml 全解析

Hatch 的全局配置文件（config.toml）用于定义工具的默认行为，包括环境路径、模板设置、终端样式等。通过修改该文件，可实现虚拟环境的本地化。

1. 配置文件的作用与位置

作用：全局配置文件是 Hatch 的 “行为准则”，所有项目的默认操作（如环境创建路径、模板生成规则）均受其约束。
位置：默认位于用户目录下的AppData\Local\hatch\config.toml（Windows 系统），可通过hatch config locate命令查看具体路径。

2. 原配置文件详解

以下是原配置文件（config.toml）的关键内容及说明：

mode = "local"                  # 工作模式："local"表示优先使用项目本地配置  
project = ""                    # 默认项目名称（留空则自动识别当前项目）  
shell = ""                      # 默认shell（留空则使用系统默认终端）  

[dirs]                          # 目录配置  
project = []                    # 额外的项目搜索目录（默认空）  
python = "isolated"             # Python解释器来源："isolated"表示使用Hatch独立管理的解释器  
data = "C:\\Users\\<用户名>\\AppData\\Local\\hatch"  # Hatch数据存储目录（含默认虚拟环境）  
cache = "C:\\Users\\<用户名>\\AppData\\Local\\hatch\\Cache"  # 缓存目录（如下载的包缓存）  

[dirs.env]                      # 虚拟环境目录（默认继承[dirs]的data路径）  

[projects]                      # 项目特定配置（默认空，需在项目内单独设置）  

[publish.index]                 # 发布配置：默认仓库名称  
repo = "main"  

[template]                      # 项目模板配置（使用`hatch new`创建项目时生效）  
name = "******"                 # 模板作者名称  
email = "******@qq.com"         # 模板作者邮箱  

[template.licenses]             # 许可证模板配置  
headers = true                  # 是否为文件自动添加许可证头部  
default = ["MIT"]               # 默认许可证类型  

[template.plugins.default]      # 默认模板插件配置  
tests = true                    # 自动生成测试目录  
ci = false                      # 不自动生成CI配置  
src-layout = true               # 使用src目录结构（项目代码放在src/下）  

[terminal.styles]               # 终端输出样式配置  
info = "bold"                   # 信息提示样式  
success = "bold cyan"           # 成功提示样式  
error = "bold red"              # 错误提示样式  
warning = "bold yellow"         # 警告提示样式  
waiting = "bold magenta"        # 等待提示样式  
debug = "bold"                  # 调试信息样式  
spinner = "simpleDotsScrolling" # 加载动画样式

五、通过修改 Hatch 的全局配置文件`实现环境储存位置的重定向`

默认配置路径：
Windows：C:\Users\<用户名>\AppData\Roaming\hatch\config.toml
可通过命令查看：

hatch config locate

要修改的配置关键调整

为实现虚拟环境本地化，核心修改是清空data和cache的固定路径，让 Hatch 根据项目位置自动生成环境目录。

修改后配置如下：

mode = "local"  
project = ""  
shell = ""  

[dirs]  
project = []  
python = "isolated"  
data = ""  # 清空固定路径，由Hatch自动适配项目位置  
cache = ""  # 清空固定路径，缓存随项目环境存放  

[dirs.env]  

# 其余配置（[projects]、[publish]、[template]、[terminal.styles]）保持不变

关键修改点说明：

清空[dirs]下的data和cache路径后，Hatch 不再强制使用 C 盘的用户目录，而是在当前项目根目录下创建虚拟环境（默认生成env文件夹）。
此配置确保环境与项目绑定，方便项目迁移（复制项目目录即可带走环境），且避免占用系统盘空间。

修改后的 config.toml 文件示例：本地化配置（推荐）

mode = "local"
project = ""
shell = ""

[dirs]
project = []
python = "isolated"
data = ""
cache = ""

[dirs.env]

[projects]

[publish.index]
repo = "main"

[template]
name = "******"
email = "******@qq.com"

[template.licenses]
headers = true
default = ["MIT"]

[template.plugins.default]
tests = true
ci = false
src-layout = true

[terminal.styles]
info = "bold"
success = "bold cyan"
error = "bold red"
warning = "bold yellow"
waiting = "bold magenta"
debug = "bold"
spinner = "simpleDotsScrolling"

关键变更回顾：

配置项	修改前	修改后	作用说明
`data`	指向用户目录	空字符串	避免写入默认目录，交由当前路径决定
`cache`	指向默认缓存路径	空字符串	避免全局缓存污染
`mode`	local	保持不变	保证环境隔离不依赖系统全局
`python`	`"isolated"`	保持不变	使用独立 Python 版本（非系统环境）

🔧 修改方式建议使用命令：
hatch config set dirs.data ""
hatch config set dirs.cache ""
hatch config set dirs.python "isolated"

六、Hatch 命令行常用语法详解

运行 hatch -h 可查看主命令帮助，以下是常用子命令简要解析：

hatch -h

Usage: hatch [OPTIONS] COMMAND [ARGS]...  # 基础语法：hatch [选项] 命令 [参数]  

Options（全局选项）：  
  -e, --env TEXT          指定要使用的环境名称（如`-e dev`表示使用dev环境）  
  -p, --project TEXT      指定项目名称（多项目管理时使用）  
  -v, --verbose           增加输出详细度（可多次使用，如`-vv`表示更详细）  
  -q, --quiet             减少输出详细度（如`-q`仅显示关键信息）  
  --color / --no-color    是否启用彩色输出（默认自动检测终端支持）  
  --interactive           是否允许交互（如提示、进度条，默认自动检测）  
  --data-dir TEXT         自定义数据目录（覆盖config.toml中的配置）  
  --cache-dir TEXT        自定义缓存目录（覆盖config.toml中的配置）  
  --config TEXT           指定自定义配置文件路径  
  --version               显示Hatch版本  
  -h, --help              显示帮助信息  

Commands（核心命令）：  
  build       打包项目（生成wheel或sdist）  
  clean       清理构建产物（如dist/、.eggs/目录）  
  config      管理配置文件（如`hatch config show`查看当前配置）  
  dep         管理依赖（如`hatch dep add requests`添加依赖）  
  env         管理虚拟环境（核心命令，如`create`创建、`remove`删除）  
  fmt         格式化代码（需配合工具如black、ruff）  
  new         创建新项目（基于模板，如`hatch new myproject`）  
  run         在环境中执行命令（如`hatch run python script.py`）  
  shell       进入环境的交互式终端（激活环境）  
  test        运行测试（需项目有测试配置）  
  version     查看或修改项目版本号

常用命令示例：

hatch env create dev：创建名为dev的开发环境。
hatch run dev:python --version：在dev环境中执行python --version。
hatch dep list：列出当前环境的所有依赖。

hatch env create dev   #：创建名为dev的开发环境。
hatch run dev:python --version   #：在dev环境中执行python --version。
hatch dep list   #：列出当前环境的所有依赖。

附：命令说明列表

命令	说明
`hatch new`	创建新项目（带模板）
`hatch env create`	创建虚拟环境（可本地化）
`hatch shell`	激活虚拟环境（进入交互式 shell）
`hatch run`	在环境中运行命令
`hatch build`	构建打包项目
`hatch publish`	发布构建产物
`hatch dep`	添加/移除依赖
`hatch fmt`	自动格式化代码
`hatch version`	查看或设置版本号
`hatch config`	管理配置文件
`hatch self`	管理 hatch 本体（如升级）

实用组合示例：

hatch new my_project          # 使用模板新建项目  
hatch env create              # 创建项目本地虚拟环境  
hatch shell                   # 进入虚拟环境交互模式  
hatch run python script.py    # 执行脚本

七、本地化创建 Hatch 虚拟环境实战

创建本地的 Hatch 虚拟环境（不创建在 C 盘，创建在项目目录内）

按照以下步骤，可在项目根目录下创建本地化的 Hatch 虚拟环境：

1. 准备工作

确保已安装 Hatch：在基础环境（如py312）中执行pip install hatch。
进入项目目录：通过终端导航到你的项目文件夹（如F:\PythonProjects\test_hatch）。

2. 具体操作步骤

1️⃣ 激活包含 hatch 的 Conda 环境：

conda activate py312

2️⃣ 项目目录中执行以下命令：

hatch env create

将自动在当前目录生成 env/ 文件夹，并部署本地虚拟环境。

3️⃣ 激活本地虚拟环境：

hatch shell

可进入隔离的 hatch 环境，提示符前缀变更表示激活成功。

4️⃣ 工具链安装：

pip install hatch

确保项目目录下环境拥有完整工具。

5️⃣ 本地化确认：

where python
where hatch

确保输出路径指向项目目录下的 env，非用户目录。

6️⃣ 退出虚拟环境：

exit

关键结果：

项目根目录下会生成env文件夹，包含完整的虚拟环境（解释器、依赖等）。
所有操作均在项目本地完成，环境路径与项目绑定。

八、PyCharm 配置 Hatch 解释器

打开 PyCharm → File → Settings → Project → Python Interpreter；
点击右上角齿轮 → Add；
选择 “Existing Environment”（现有环境）,类型选“Hatch”；
浏览路径选择： <项目目录>\env\virtual\<项目名>\Scripts\hatch.exe；
应用并确定，PyCharm 即可识别本地 Hatch 环境。

验证：配置完成后，PyCharm 右下角会显示当前解释器为项目本地的 Hatch 环境。

九、关键操作步骤回顾（最佳实践）

总结 Hatch 项目本地环境的主要操作步骤

基础环境准备：激活安装 Hatch 的基础环境（如conda activate py312）。
修改全局配置：清空config.toml中[dirs]下的data和cache路径，确保环境本地化。
创建本地环境：在项目目录执行hatch env create，生成env文件夹。
激活与使用：通过hatch shell进入环境，使用hatch run执行命令。
IDE 配置：在 PyCharm 中指定<项目目录>\env\virtual\<项目名>\Scripts\hatch.exe作为hatch识别路径。

回顾 Hatch 项目本地环境的详细操作步骤

步骤	操作命令	说明
1	`conda activate py312`	切入包含 hatch 的基础环境
2	`hatch config set dirs.data ""`	配置 data 路径为空
3	`hatch config set dirs.cache ""`	配置 cache 路径为空
4	`cd 项目目录`	切换至目标项目路径
5	`hatch env create`	创建本地虚拟环境
6	`hatch shell`	进入本地 hatch 环境
7	`pip install hatch`	确保本地环境工具链独立
8	`where python` / `where hatch`	路径确认与验证