1.配置环境挑战 #

你是否遇到过这样的困扰？拿到一个 Python 项目，光是配置环境就让人头大：

• Python 版本不兼容，官网/apt/pyenv 各种装；
• 虚拟环境 virtualenv/venv/conda，傻傻分不清；
• 依赖管理 pip/pipenv/poetry，工具一大堆；
• 工具类依赖（如 ruff/pytest）和项目依赖混在一起，环境一团乱麻。

为什么 Python 开发环境如此分裂？难道没有一站式解决方案吗？

有！它的名字就是 UV。

2. UV 是什么？ #

UV 是一个集成了 Python 版本管理、虚拟环境、依赖管理、工具安装与项目打包的全能工具。用 UV，你可以：

• 安装/切换任意 Python 版本
• 一键创建虚拟环境
• 管理项目依赖和开发依赖
• 独立安装/管理命令行工具
• 打包并发布你的 Python 项目

3. 安装 UV #

pip install uv

4. 常用命令速查 #

功能	命令示例
列出支持的 Python	uv python list
安装 Python 3.12	uv python install cpython3.12
用指定版本运行脚本	uv run -p 3.12 xxx.py
进入指定版本交互环境	uv run -p 3.12 python
用虚拟环境运行脚本	uv run xxx.py
创建新工程	uv init -p 3.12
添加依赖	uv add pydantic_ai
查看依赖树	uv tree
移除依赖	uv remove pydantic_ai
编译打包	uv build

5. 实战 #

5.1 新建工程 #

uv init

UV 会自动创建项目结构，并生成 .python-version 文件记录 Python 版本。

5.2 安装依赖 #

比如 main.py 依赖 flask：

uv add flask

依赖会被写入 pyproject.toml，UV 也会自动创建虚拟环境（.venv）。

5.3 运行脚本 #

uv run main.py

此时 VS Code 右下角选择虚拟环境的 Python 解释器，代码提示和依赖都能正常工作。

5.4 查看依赖树 #

uv tree

一目了然所有依赖关系。

5.6 移除依赖 #

uv remove flask

6. 打包与发布 #

编辑 pyproject.toml，在 [project.scripts] 部分添加：

格式：命令名 = "模块名:函数名"

[project.scripts]
main = "main:main"

然后打包：

uv build

会生成 .whl 文件，可上传 PyPI 或本地安装。

本地安装并生成全局命令：

uv tool install dist\uvproject-0.1.0-py3-none-any.whl
main

7. toml #

在 Python 项目中，pyproject.toml 是用于定义项目元数据、依赖和可执行脚本的配置文件。通过 [project.scripts] 部分，你可以定义命令行工具，使其在安装后可以直接在终端运行。

7.1. [project.scripts] 的作用 #

• 定义 可执行命令（CLI 工具）
• 类似于 setup.py 中的 entry_points
• 当用户 pip install 你的包时，这些命令会被安装到 PATH，可以直接在终端运行

7.2. 如何编辑 pyproject.toml 添加脚本？ #

在你的 pyproject.toml 文件中，添加 [project.scripts] 部分，并定义命令名称和对应的 Python 模块+函数：

[project.scripts]
# 格式：命令名 = "模块名:函数名"
main = "main:main"

7.3. 解释 #

• main → 终端中运行的命令（如 $ main）
• "main:main" → 表示从 main.py 文件导入 main() 函数

8.whl #

.whl 文件（Wheel 文件）是 Python 的二进制分发格式，用于更高效地安装 Python 包。它是现代 Python 包管理的标准格式，取代了旧的 .egg 格式。

8.1. 什么是 Wheel 文件？ #

Wheel（.whl）是 Python 的一种内置包格式，包含：

• 编译好的 Python 代码（.pyc 文件）
• 包的元数据
• 依赖信息
• 可能的本地扩展模块（如 C 扩展）

8.2. Wheel 文件的命名规范 #

一个典型的 wheel 文件名格式为：

{distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl

例如：

numpy-1.21.2-cp39-cp39-win_amd64.whl

解释：

• numpy: 包名
• 1.21.2: 版本号
• cp39: Python 3.9
• cp39: ABI 标签
• win_amd64: Windows 64位平台

8.3. Wheel 文件的优势 #

1. 安装更快：不需要在安装时编译代码
2. 更可靠：避免了编译过程中的潜在问题
3. 支持跨平台：有特定平台的 wheel 文件
4. 支持并行安装：多个 wheel 可以同时安装

8.5. 如何使用 Wheel 文件 #

8.5.1 安装 Wheel 文件 #

pip install package_name.whl

8.5.2 从源代码构建 Wheel #

pip wheel .

8.5.3 下载但不安装 #

pip download package_name --only-binary=:all:

8.6. Wheel 文件的结构 #

解压一个 wheel 文件后，通常包含：

package_name/
├── package/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── package-version.dist-info/
│   ├── METADATA
│   ├── RECORD
│   ├── WHEEL
│   └── top_level.txt
└── 可能的其他文件