【5分钟教程】用 `uv` 构建现代 Python 项目：从目录结构到打包测试一条龙

🎯 本文将带你一步步构建一个兼容 PEP 标准、快如闪电、结构清晰、测试完善的 Python 工程体系，替代 pip、setuptools、conda、setup.py 等传统方式。整合 uv + pyproject.toml + ruff + pytest + coverage 一体化开发体验。

📁 项目结构总览

我们采用社区推荐的 src/ 布局，结合 pyproject.toml 配置，形成如下目录：

 awesome-project/
├── pyproject.toml          # ✅ 全局配置，替代 setup.py
├── requirements.txt        # ✅ 可选，兼容 pip
├── uv.lock                 # ✅ uv 快照（可选）
├── .venv/                  # ✅ 本地虚拟环境（uv venv 创建）
├── src/
│   └── awesome/            # ✅ 你的项目代码（支持多包）
│       └── __init__.py
├── tests/                  # ✅ 测试目录（pytest 自动发现）
│   └── test_example.py
├── ruff.toml               # ✅ 代码风格配置
└── README.md               # ✅ 项目说明（包含安装、使用、发布）

🛠️ 步骤 1：使用 uv 创建虚拟环境与安装依赖

 # 初始化项目目录
mkdir awesome-project && cd awesome-project
 
# 创建本地虚拟环境
uv venv .venv
source .venv/bin/activate
 
# 安装核心依赖
uv pip install requests fastapi
 
# 安装开发依赖
uv pip install pytest coverage ruff
 
# 快照依赖（可选）
uv snapshot

⚙️ 步骤 2：配置 pyproject.toml（替代 setup.py）

 [project]
name = "awesome"
version = "0.1.0"
description = "A blazing-fast uv-powered Python project"
readme = "README.md"
authors = [{name = "Feilong", email = "feilong@example.com"}]
requires-python = ">=3.9"
dependencies = ["requests", "fastapi"]
 
[project.optional-dependencies]
dev = ["pytest", "coverage", "ruff"]
 
[build-system]
requires = ["uv"]
build-backend = "uv.build"

🎯 步骤 3：代码质量工具（ruff）配置

创建 ruff.toml：

 [tool.ruff]
src = ["src"]
line-length = 100
target-version = "py39"

格式化与检查：

 ruff check src tests
ruff format src tests

🧪 步骤 4：测试与覆盖率（pytest + coverage）

新增配置（可合并进 pyproject.toml）：

 [tool.pytest.ini_options]
addopts = "--tb=short -q"
testpaths = ["tests"]
 
[tool.coverage.run]
branch = true
source = ["src/awesome"]
 
[tool.coverage.report]
show_missing = true

运行：

 pytest
coverage run -m pytest
coverage report -m

📦 步骤 5：构建与发布（uv build + twine）

构建产物

 uv build

构建完成后生成：

 dist/
├── awesome-0.1.0-py3-none-any.whl
├── awesome-0.1.0.tar.gz

发布 PyPI（使用 twine）

 pip install twine
twine upload dist/*

可选 .pypirc：

 [distutils]
index-servers = pypi
 
[pypi]
username = __token__
password = pypi-<your-token>

✅ 可选：开发者模式安装

用于边写边测试：

 uv pip install -e .

🚦 Github Actions 自动化（CI）

 # .github/workflows/test.yml
name: Test & Build
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.9'
      - name: Install uv
        run: pip install uv
      - name: Install deps
        run: uv pip install .[dev]
      - name: Lint
        run: ruff check src tests
      - name: Test
        run: coverage run -m pytest
      - name: Coverage Report
        run: coverage report -m
      - name: Build
        run: uv build

🧠 总结

能力	传统工具	uv 工具链替代
虚拟环境	`venv` / `conda`	`uv venv`
安装依赖	`pip` / `poetry`	`uv pip install`
构建发布包	`setup.py` + `wheel`	`pyproject.toml` + `uv build`
开发模式安装	`pip install -e .`	`uv pip install -e .`
代码风格	`flake8` + `isort` + `black`	`ruff`
测试覆盖	`pytest + coverage`	同上，自动集成
发布 PyPI	`twine upload`	`uv build` + `twine upload`

--end--

posted @ 2025-07-03 21:16 ffl 阅读(77) 评论(0) 收藏举报

刷新页面返回顶部

（评论功能已被禁用）

相关博文：

· 远程小组软件开发过程(2):工具

· CleanCode(1): 编写干净清晰的 Python 代码的一种通用模块设计

· 拥抱未来：下一代 Python 打包工具 uv 使用指南

· 现代 Python 包管理器 uv

· Python包管理不再头疼：uv工具快速上手

阅读排行：
· 推荐 5 款实用的 Docker 可视化管理工具，工作效率翻倍！
· 瞧瞧别人家的接口重试，那叫一个优雅！
· 哥们儿，别光顾着修 Bug，你的人生系统也该打个养老补丁了！
· 独立开发第二周：构建、执行、规划
· JavaScript面试题，为什么[] + 0 = '0', 而{} + 0 = 0?

Feilong's Blog

捕捉极限技术，关注微博 @幻灰龙保持改变的能力，探索无尽的前沿

【5分钟教程】用 `uv` 构建现代 Python 项目：从目录结构到打包测试一条龙

📁 项目结构总览

🛠️ 步骤 1：使用 uv 创建虚拟环境与安装依赖

⚙️ 步骤 2：配置 pyproject.toml（替代 setup.py）

🎯 步骤 3：代码质量工具（ruff）配置

🧪 步骤 4：测试与覆盖率（pytest + coverage）

📦 步骤 5：构建与发布（uv build + twine）

构建产物

发布 PyPI（使用 twine）

✅ 可选：开发者模式安装

🚦 Github Actions 自动化（CI）

🧠 总结

公告

搜索

我的标签

积分与排名

随笔档案 (260)

阅读排行榜

评论排行榜

最新评论

	awesome-project/
	├── pyproject.toml # ✅ 全局配置，替代 setup.py
	├── requirements.txt # ✅ 可选，兼容 pip
	├── uv.lock # ✅ uv 快照（可选）
	├── .venv/ # ✅ 本地虚拟环境（uv venv 创建）
	├── src/
	│ └── awesome/ # ✅ 你的项目代码（支持多包）
	│ └── __init__.py
	├── tests/ # ✅ 测试目录（pytest 自动发现）
	│ └── test_example.py
	├── ruff.toml # ✅ 代码风格配置
	└── README.md # ✅ 项目说明（包含安装、使用、发布）

	# 初始化项目目录
	mkdir awesome-project && cd awesome-project

	# 创建本地虚拟环境
	uv venv .venv
	source .venv/bin/activate

	# 安装核心依赖
	uv pip install requests fastapi

	# 安装开发依赖
	uv pip install pytest coverage ruff

	# 快照依赖（可选）
	uv snapshot

	[project]
	name = "awesome"
	version = "0.1.0"
	description = "A blazing-fast uv-powered Python project"
	readme = "README.md"
	authors = [{name = "Feilong", email = "feilong@example.com"}]
	requires-python = ">=3.9"
	dependencies = ["requests", "fastapi"]

	[project.optional-dependencies]
	dev = ["pytest", "coverage", "ruff"]

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

	[tool.ruff]
	src = ["src"]
	line-length = 100
	target-version = "py39"

	[tool.pytest.ini_options]
	addopts = "--tb=short -q"
	testpaths = ["tests"]

	[tool.coverage.run]
	branch = true
	source = ["src/awesome"]

	[tool.coverage.report]
	show_missing = true

	dist/
	├── awesome-0.1.0-py3-none-any.whl
	├── awesome-0.1.0.tar.gz

	[distutils]
	index-servers = pypi

	[pypi]
	username = __token__
	password = pypi-<your-token>

	# .github/workflows/test.yml
	name: Test & Build

	jobs:
	build:
	runs-on: ubuntu-latest
	steps:
	- uses: actions/checkout@v4
	- uses: actions/setup-python@v5
	with:
	python-version: '3.9'
	- name: Install uv
	run: pip install uv
	- name: Install deps
	run: uv pip install .[dev]
	- name: Lint
	run: ruff check src tests
	- name: Test
	run: coverage run -m pytest
	- name: Coverage Report
	run: coverage report -m
	- name: Build
	run: uv build

Feilong's Blog

捕捉极限技术，关注微博 @幻灰龙 保持改变的能力，探索无尽的前沿

【5分钟教程】用 `uv` 构建现代 Python 项目：从目录结构到打包测试一条龙

📁 项目结构总览

🛠️ 步骤 1：使用 uv 创建虚拟环境与安装依赖

⚙️ 步骤 2：配置 pyproject.toml（替代 setup.py）

🎯 步骤 3：代码质量工具（ruff）配置

🧪 步骤 4：测试与覆盖率（pytest + coverage）

📦 步骤 5：构建与发布（uv build + twine）

构建产物

发布 PyPI（使用 twine）

✅ 可选：开发者模式安装

🚦 Github Actions 自动化（CI）

🧠 总结

公告

搜索

我的标签

积分与排名

随笔档案 (260)

阅读排行榜

评论排行榜

最新评论

捕捉极限技术，关注微博 @幻灰龙保持改变的能力，探索无尽的前沿