告别requirements.txt！用uv和pyproject.toml打造更优雅的Python依赖管理（附迁移实战）

告别requirements.txt！用uv和pyproject.toml打造更优雅的Python依赖管理（附迁移实战）

如果你是一位Python开发者，大概率经历过这样的场景：接手一个老项目，面对一个臃肿不堪、动辄上百行的requirements.txt文件，里面混杂着直接依赖、间接依赖，甚至还有早已被弃用的包。你想更新某个库，却不知道哪些是真正需要的，哪些是“历史遗留物”。更别提团队协作时，因为锁定的版本不一致，导致“在我机器上好好的”这种经典问题反复上演。这种依赖管理的混乱，早已成为现代Python开发中一个亟待解决的痛点。

今天，我们不再需要忍受这种混乱。以uv为代表的新一代工具，结合社区标准pyproject.toml，正在重塑Python依赖管理的体验。这不仅仅是换一个工具那么简单，而是一次开发理念的升级——从“能用就行”的脚本思维，转向“清晰、可复现、可协作”的工程化思维。本文将带你深入理解为何要迁移，如何平滑迁移，以及迁移后能为你的项目和团队带来哪些长期、深远的收益。无论你是独立开发者，还是团队的决策者，这篇文章都将为你提供一份清晰的路线图。

1. 为什么我们必须告别requirements.txt？

requirements.txt文件伴随Python开发者多年，其简单直接的格式（一行一个包）降低了入门门槛。然而，随着项目复杂度提升和团队协作成为常态，它的设计缺陷日益凸显，成为项目维护的“技术债”源头。

1.1 requirements.txt的三大“原罪”

首先，让我们直面requirements.txt的根本问题。这些问题并非偶然，而是由其设计哲学决定的。

依赖声明与锁定的混淆：这是最核心的问题。一个健康的依赖管理应该区分“我想要什么”（声明）和“我最终得到了什么”（锁定）。requirements.txt将两者强行合并。当你运行pip freeze > requirements.txt时，你得到的是当前虚拟环境中所有包的精确版本，包括所有间接依赖（即你的依赖所依赖的包）。这导致文件迅速膨胀，且你无法区分哪些是你主动引入的核心功能，哪些是底层库的附带品。

# 一个典型的、由pip freeze生成的混乱requirements.txt片段
asgiref==3.8.1
Django==5.0.6
sqlparse==0.5.0
tzdata==2024.1
# 请问，哪个是项目的直接依赖？哪些是间接依赖？

缺乏环境隔离与分组能力：一个真实的项目需要多种环境：开发、测试、构建、文档、生产。开发环境可能需要代码格式化、测试框架、调试工具；生产环境则只需要最精简的运行时依赖。requirements.txt对此无能为力。常见的“解决方案”是维护多个文件，如requirements-dev.txt、requirements-prod.txt，但这带来了同步和版本一致性的新问题。

可复现性陷阱：即使你使用了pip install -r requirements.txt，也无法保证在不同时间、不同机器上获得完全相同的依赖树。因为requirements.txt中可能包含版本范围（如requests>=2.25）或未锁定的间接依赖。细微的版本差异可能导致难以调试的兼容性问题，这就是“works on my machine”的经典根源。

注意：许多团队试图通过严格使用pip freeze并锁定所有版本来解决可复现性问题，但这恰恰加剧了第一个问题——依赖声明的混淆，使得后续的依赖升级和审计变得异常困难。

1.2 现代依赖管理的核心原则

在批评旧工具的同时，我们更需要理解新一代工具所遵循的原则。这些原则并非uv独有，而是整个生态（如Poetry, PDM）的共识，并体现在PEP标准中。

• 声明与锁定分离：在pyproject.toml中声明项目的直接依赖（你主动需要的功能），工具自动生成一个锁文件（如uv.lock、poetry.lock）来记录所有依赖（包括间接依赖）的确切版本。这就像package.json和package-lock.json的关系。
• 确定性与可复现性：锁文件保证了在任何地方、任何时候安装的依赖树完全一致，彻底消灭环境差异。
• 依赖分组：支持为不同用途定义依赖组，实现环境的精细化管理。
• 符合社区标准：pyproject.toml（PEP 621）已成为Python项目配置的事实标准，统一了打包、依赖管理等元数据，得到主流工具链的支持。

下面的表格清晰地对比了传统模式与现代模式的核心差异：