Pythonrequirements.txt替代方案详解

Python 的 requirements.txt 已不再是现代生产环境推荐的依赖管理方式——它仅是扁平化、无上下文的安装快照，无法追踪依赖来源、区分环境、表达条件逻辑或保证跨平台/跨工具的可重现性；真正的解决方案是转向以 pyproject.toml 声明源依赖、配合带哈希与元数据（如 Python 版本、操作系统）的锁文件（如 poetry.lock 或 requirements.lock），借助 Poetry、pip-tools 或 uv 等工具实现可审计、可复现、可协作的依赖治理——迁移的关键不在换命令，而在于厘清“声明”与“锁定”的本质分离，并让整个团队理解：一份可靠的依赖合约，必须包含足够上下文，而非仅仅一串版本号。

requirements.txt 为什么不再被推荐作为生产依赖管理方式

Python 官方（PEP 621、pip 23.1+）和主流工具链（poetry、pip-tools、uv）已明确将 requirements.txt 视为“扁平化导出产物”，而非源声明。它不记录依赖来源（是直接安装的？还是子依赖？）、不区分开发/生产环境、无法表达条件依赖（如 platform_system == "Windows"），更不支持可重现的锁机制——你看到的 requests==2.31.0 可能来自不同版本的 setuptools 解析，导致本地与 CI 行为不一致。

• requirements.txt 是“快照”，不是“合约”
• 它没有元数据字段（比如作者、分类器、Python 版本约束）
• 所有依赖都被压平，丢失层级关系，pip install -r requirements.txt 实际执行的是无上下文的线性安装

替代方案：pyproject.toml + 依赖锁文件（如 requirements.lock 或 poetry.lock）

现在标准做法是用 pyproject.toml 声明项目元信息和直接依赖，再由工具生成带哈希、平台、Python 版本标记的锁文件。这解决了 requirements.txt 的核心缺陷：不可重现、不可追溯、不可分组。

• 使用 pip-tools：写 pyproject.toml 或 requirements.in，运行 pip-compile --resolver=backtracking 生成带哈希的 requirements.txt（注意：这只是兼容层，实际应叫 requirements.lock）
• 使用 poetry：pyproject.toml 中写 [tool.poetry.dependencies]，运行 poetry lock 生成 poetry.lock
• 使用 uv：uv pip compile pyproject.toml -o requirements.lock，速度更快，解析更严格

迁移时最容易踩的三个坑

很多团队在“把旧 requirements.txt 搬进 pyproject.toml”时掉进细节陷阱：

• 直接复制粘贴版本号到 [project.dependencies]，却没处理 -e . 或 git+https://... 这类 VCS 依赖——它们必须改写成 PEP 508 格式，例如："mylib @ git+https://github.com/user/repo@v1.2.3"
• 忽略 python 字段约束：[project.requires-python] = ">=3.9" 缺失会导致不同环境中解析出不同依赖树
• 把 dev-requirements.txt 简单合并进主依赖——应该用 [project.optional-dependencies]（如 dev = ["pytest", "black"]），再通过 pip install ".[dev]" 安装

CI/CD 和容器镜像里怎么安全用新流程

Dockerfile 或 GitHub Actions 里继续写 pip install -r requirements.txt 是倒退。正确路径是：

• 构建阶段用 uv sync 或 poetry install --no-dev，它会读取锁文件并跳过解析
• 不再 COPY requirements.txt .，而是 COPY pyproject.toml poetry.lock .（或 requirements.lock）
• 若必须保留 requirements.txt 名称（比如某些平台强制要求），就把它当成锁文件别名，但内容必须带哈希、来源注释，并禁止手动编辑

真正难的不是换工具，是让所有人理解：依赖声明和依赖锁定必须分离，且锁定必须包含足够上下文。否则只是把 requirements.txt 换个名字，问题还在。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Pythonrequirements.txt替代方案详解》文章吧，也可关注golang学习网公众号了解相关技术文章。