Hatch 完整指南：Python 现代化构建、打包、环境管理工具

评论
1 views

Hatch 完整指南：Python 现代化构建、打包、环境管理工具

一、Hatch 是什么

Hatch 是 Python 官方推荐、现代一体化项目管理工具，替代 pipenv/poetry/setuptools/pip，一站式搞定： - 虚拟环境隔离（多 Python 版本并行） - 项目打包、构建 sdist/wheel - 依赖管理、锁定文件 - 脚本命令、测试、格式化、发布 PyPI - 多子包/单包、库/CLI 工具模板

底层标准完全贴合 PEP 621（pyproject.toml 标准化项目配置），抛弃老旧 setup.py/setup.cfg。

核心优势对比 Poetry/Pipenv

  1. 速度更快，环境隔离轻量化
  2. 原生支持多 Python 版本测试
  3. 内置项目模板（库、CLI、插件）
  4. 区分项目依赖 / 开发依赖 / 测试依赖，粒度更细
  5. 构建产物干净，无冗余配置文件
  6. 支持工作区（workspace）多包单体仓库

二、安装 Hatch

全局安装（推荐）

# pip 安装
pip install hatch

# 官方独立安装脚本（跨平台，不污染系统 Python）
curl -fsSL https://hatch.pypa.io/install.ps1 | python3 -

验证：

hatch --version

三、快速创建新项目

1. 新建标准 Python 库

hatch new mypkg
cd mypkg

自动生成目录结构：

mypkg/
├── pyproject.toml   # 唯一配置文件（PEP621）
├── src/
│   └── mypkg/       # 源码包
│       └── __init__.py
├── tests/           # 测试目录
└── README.md

2. 创建 CLI 命令行工具项目

hatch new --cli mycli

自动配置控制台入口，安装后可直接 mycli 调用。

四、核心配置：pyproject.toml

基础标准配置示例

[build-system]
requires = ["hatchling>=1.18"]
build-backend = "hatchling.build"

# PEP621 项目元信息
[project]
name = "mypkg"
version = "0.1.0"
authors = [{ name = "Your Name", email = "xxx@mail.com" }]
description = "Demo package managed by hatch"
requires-python = ">=3.9"
dependencies = [
    "requests>=2.30"
]

# 开发/测试依赖（不随包发布）
[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "ruff",
    "black"
]

# CLI 入口（--cli 模板自动生成）
[project.scripts]
mycmd = "mypkg.cli:main"

# Hatch 专属配置
[tool.hatch.envs.default]
dependencies = [
    "{dev}"  # 引用上面 optional-dependencies.dev
]

五、虚拟环境管理（Hatch 核心能力）

1. 进入默认环境

hatch shell

自动创建 .hatch/ 缓存虚拟环境，退出输入 exit。

2. 不进入环境，单次执行命令

# 运行测试
hatch run pytest
# 格式化代码
hatch run ruff check src/
hatch run black src/

3. 多 Python 版本并行环境

本地装有 Python3.9 / 3.10 / 3.11，可创建多环境：

# pyproject.toml
[tool.hatch.envs.py39]
python = "3.9"
dependencies = ["{dev}"]

[tool.hatch.envs.py311]
python = "3.11"
dependencies = ["{dev}"]

执行指定环境命令：

hatch -e py39 run pytest
hatch -e py311 run pytest

常用环境命令

# 列出所有环境
hatch env show
# 删除环境
hatch env remove py39
# 更新依赖
hatch env update

六、依赖管理

1. 添加运行时依赖（打包会携带）

hatch add requests

2. 添加开发依赖（仅本地，不发布）

hatch add --dev ruff pytest

3. 锁定依赖

Hatch 自动生成 hatch-lock 文件，锁定所有依赖精确版本：

hatch env lock

他人拉取代码一键同步环境：

hatch env sync

七、构建打包（核心构建工具功能）

1. 构建 sdist（源码包）+ wheel（二进制分发包）

hatch build

产物输出到 dist/ 目录： - .tar.gz：源码分发包 - .whl：wheel 安装包

2. 仅构建 wheel

hatch build --wheel

3. 清理构建产物

hatch clean

构建配置自定义（文件包含/排除）

[tool.hatch.build]
include = ["src/**/*.py", "README.md"]
exclude = ["tests/", "docs/", "*.mdc"]

# 数据文件打包
[tool.hatch.build.targets.wheel]
packages = ["mypkg"]

八、发布到 PyPI

1. 本地校验包合规性

hatch publish --check

2. 发布到官方 PyPI

hatch publish

3. 发布到 TestPyPI 测试

hatch publish --repo testpypi

九、脚本命令封装

在 pyproject.toml 自定义快捷命令，替代 Makefile：

[tool.hatch.envs.default.scripts]
test = "pytest -v"
lint = "ruff check src/"
fmt = "black src/"
ci = ["ruff check src/", "black --check src/", "pytest"]

调用：

hatch run test
hatch run ci

十、工作区 Workspace（多包单体仓库）

适合 monorepo 多子包场景，根目录创建 hatch.toml：

[workspace]
members = [
    "packages/*",
    "apps/cli"
]

统一批量构建、测试所有子包：

# 全部构建
hatch build --workspace
# 全部测试
hatch run --workspace test

十一、常用完整命令速查表

功能 命令
创建项目 hatch new name / hatch new --cli name
进入虚拟环境 hatch shell
环境执行命令 hatch run xxx
添加依赖 hatch add pkg / hatch add --dev pkg
构建分发包 hatch build
清理构建文件 hatch clean
发布 PyPI hatch publish
查看环境 hatch env show
格式化/测试 hatch run fmt / hatch run test

十二、与 Poetry / setuptools 对比总结

  1. Setuptools：仅打包，无环境/依赖锁定，配置繁琐
  2. Poetry：一体化，但体积大、多版本环境支持弱、速度慢
  3. Hatch：轻量化、官方标准、多环境原生支持、workspace 多包、构建速度快，是目前 Python 最现代化构建工具

十三、适用场景

  • 个人 Python 库、开源项目发布
  • CLI 命令行工具开发
  • 多 Python 版本兼容测试
  • Monorepo 多包项目管理
  • 替代 pipenv/poetry 做本地开发环境管理