Hatch Python 项目管理¶

一句话说明： Hatch 是 PyPA（Python Packaging Authority）官方维护的现代 Python 项目管理工具，统一了构建、测试、发布、环境管理和版本控制。

为什么要学¶

PyPA 官方出品 — PEP 标准的参考实现，与 Python 生态深度集成
统一工具链 — 构建、测试、格式化、发布一个工具搞定，不再拼凑多个工具
标准化元数据 — 完全基于 pyproject.toml（PEP 621），面向未来
灵活的环境矩阵 — 轻松定义多 Python 版本 x 多依赖组合的测试矩阵
版本管理 — 内置语义化版本控制，支持从 VCS tag 自动推导版本号

核心概念详解¶

与其他工具对比¶

特性	Hatch	Poetry	PDM	Flit
官方维护	PyPA	社区	社区	PyPA
构建后端	hatchling	poetry-core	pdm-backend	flit-core
环境管理	内置（多环境）	内置（单环境）	内置	无
版本管理	内置	内置	插件	无
测试矩阵	原生支持	无	无	无
Lock 文件	uv 集成	有	有	无
PEP 621	完全遵循	部分	完全	完全

核心概念¶

概念	说明	类比
Environment	隔离的开发/测试环境	virtualenv
Script	环境中可执行的命令	npm scripts
Matrix	多维度测试组合	tox
Build target	构建产物（sdist/wheel）	setup.py build
Version scheme	版本号策略	bumpversion

项目结构¶

my-project/
├── pyproject.toml      # 所有配置的唯一入口
├── src/
│   └── my_project/
│       ├── __init__.py
│       └── main.py
├── tests/
│   ├── __init__.py
│   └── test_main.py
└── README.md

安装与配置¶

安装 Hatch¶

# pipx（推荐，全局隔离安装）
pipx install hatch

# pip
pip install hatch

# Homebrew
brew install hatch

# conda
conda install -c conda-forge hatch

全局配置¶

# 查看配置路径
hatch config find

# 设置默认用户名和邮箱
hatch config set template.name "Your Name"
hatch config set template.email "you@example.com"

Shell 补全¶

# Bash
hatch --install-completion bash

# Zsh
hatch --install-completion zsh

# Fish
hatch --install-completion fish

验证¶

hatch --version
# Hatch, version 1.13.0

快速上手¶

创建新项目¶

hatch new my-project
cd my-project

生成的 pyproject.toml：

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

[project]
name = "my-project"
version = "0.1.0"
description = ""
readme = "README.md"
requires-python = ">=3.9"
license = "MIT"
authors = [
    { name = "Your Name", email = "you@example.com" },
]
dependencies = []

[project.urls]
Homepage = "https://github.com/you/my-project"

添加依赖¶

直接编辑 pyproject.toml：

[project]
dependencies = [
    "requests>=2.28",
    "click>=8.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "ruff>=0.1",
]

基本操作¶

# 进入默认环境 shell
hatch shell

# 在环境中运行命令
hatch run python main.py
hatch run pytest tests/

# 构建包
hatch build

# 发布到 PyPI
hatch publish

进阶用法¶

1. 多环境定义¶

# pyproject.toml 或 hatch.toml

[tool.hatch.envs.default]
dependencies = [
    "pytest",
    "pytest-cov",
]

[tool.hatch.envs.default.scripts]
test = "pytest {args:tests}"
cov = "pytest --cov=src --cov-report=term-missing {args:tests}"

[tool.hatch.envs.lint]
detached = true  # 不安装项目本身
dependencies = [
    "ruff>=0.5",
    "mypy>=1.0",
]

[tool.hatch.envs.lint.scripts]
check = [
    "ruff check .",
    "mypy src/",
]
fix = "ruff check --fix ."
format = "ruff format ."

[tool.hatch.envs.docs]
dependencies = [
    "mkdocs",
    "mkdocs-material",
]

[tool.hatch.envs.docs.scripts]
serve = "mkdocs serve"
build = "mkdocs build"

使用：

hatch run test                    # 默认环境跑测试
hatch run lint:check             # lint 环境跑检查
hatch run docs:serve             # docs 环境跑文档
hatch run cov -- -v              # 传参数

2. 测试矩阵¶

[tool.hatch.envs.test]
dependencies = [
    "pytest",
    "pytest-cov",
]

[[tool.hatch.envs.test.matrix]]
python = ["3.9", "3.10", "3.11", "3.12"]

[tool.hatch.envs.test.scripts]
run = "pytest {args}"

# 在所有 Python 版本上运行测试
hatch run test:run

# 只在 3.12 上运行
hatch run +py=3.12 test:run

3. 版本管理¶

[tool.hatch.version]
path = "src/my_project/__init__.py"
# 版本号从 __init__.py 的 __version__ 读取

# src/my_project/__init__.py
__version__ = "0.1.0"

# 查看当前版本
hatch version

# 递增版本
hatch version patch   # 0.1.0 → 0.1.1
hatch version minor   # 0.1.1 → 0.2.0
hatch version major   # 0.2.0 → 1.0.0

# 设置具体版本
hatch version "2.0.0rc1"

4. 从 VCS 自动版本¶

[tool.hatch.version]
source = "vcs"  # 从 git tag 推导

[tool.hatch.build.hooks.vcs]
version-file = "src/my_project/_version.py"

git tag v1.0.0
hatch version  # 自动读取 1.0.0

5. CLI 入口点¶

[project.scripts]
my-cli = "my_project.cli:main"

[project.gui-scripts]
my-gui = "my_project.gui:main"

6. 构建配置¶

[tool.hatch.build.targets.sdist]
include = ["src/", "tests/"]

[tool.hatch.build.targets.wheel]
packages = ["src/my_project"]

# 构建钩子（如编译 Cython）
[tool.hatch.build.hooks.custom]
path = "build_hooks.py"

# 构建
hatch build
# 产出:
#   dist/my_project-0.1.0.tar.gz  (sdist)
#   dist/my_project-0.1.0-py3-none-any.whl  (wheel)

7. 发布到 PyPI¶

# 首次配置 PyPI token
hatch config set publish.index.repos.main.url https://upload.pypi.org/legacy/
hatch config set publish.index.repos.main.username __token__
hatch config set publish.index.repos.main.password pypi-xxxxxxx

# 发布
hatch publish

# 发布到 TestPyPI
hatch publish -r test

8. 与 uv 集成（加速）¶

# 使用 uv 作为安装器（速度更快）
[tool.hatch.envs.default]
installer = "uv"

常见问题与排错¶

Q: "Environment already exists"¶

# 删除环境重建
hatch env remove default
hatch env create

Q: 如何使用已有 virtualenv¶

Hatch 管理自己的环境。如需使用系统 Python：

[tool.hatch.envs.default]
type = "virtual"
python = "/usr/bin/python3.11"

Q: pyproject.toml 配置不生效¶

确认 section 名正确： - 项目元数据：[project] - Hatch 配置：[tool.hatch.*] - 构建系统：[build-system]

Q: 如何迁移 setup.py 项目¶

# 使用 hatch 生成 pyproject.toml 后手动迁移
# 关键步骤：
# 1. 将 setup() 参数转为 [project] 字段
# 2. 设置 build-system 为 hatchling
# 3. 删除 setup.py, setup.cfg

Q: 构建时包含/排除文件¶

[tool.hatch.build.targets.sdist]
include = ["src/", "LICENSE", "README.md"]
exclude = ["tests/fixtures/large_data/"]

Q: 环境内 import 找不到项目包¶

确保项目以可编辑模式安装（Hatch 默认行为）。检查 packages 配置：

[tool.hatch.build.targets.wheel]
packages = ["src/my_project"]

参考资源¶

官方文档：https://hatch.pypa.io/latest/
GitHub 仓库：https://github.com/pypa/hatch
Hatchling 构建后端：https://hatch.pypa.io/latest/plugins/builder/wheel/
PEP 621 规范：https://peps.python.org/pep-0621/
PyPA 打包指南：https://packaging.python.org/en/latest/
迁移指南：https://hatch.pypa.io/latest/how-to/migrate/