基于pyproject.toml的Python应用依赖管理最佳实践咨询

针对你提出的三种方案，结合应用开发对依赖可复现性和开发效率的需求，第三种方案确实是最合理的选择。下面逐一拆解各方案的优劣，并给出纯pip+pyproject.toml的极简配置步骤：

方案优劣对比 #

1. requirements.txt存固定依赖，pyproject.toml引用 #

• 优势：生产环境能完全复现依赖版本，避免子依赖版本差异导致的问题
• 劣势：缺少明确的顶层依赖声明，其他开发者无法快速知晓项目核心依赖；开发时更新依赖后需手动执行freeze，流程不够顺畅

2. 仅pyproject.toml固定顶层依赖 #

• 优势：配置单一集中，无需额外文件
• 劣势：生产环境安装时，pip会动态解析子依赖版本，不同环境（如不同系统、不同pip版本）可能得到不一致的依赖树，无法保证完全可复现

3. requirements.txt存固定依赖 + pyproject.toml引用+可选开发依赖 #

• 优势：完美平衡可复现性与开发效率——开发时用未固定的顶层依赖快速迭代，推送前通过freeze锁定全量依赖版本；同时pyproject.toml里的开发依赖能清晰展示项目核心依赖
• 劣势：需要维护两个文件，但操作流程简单，额外工作量极小

极简配置步骤 #

1. 编写pyproject.toml #

在项目根目录创建pyproject.toml，配置核心依赖引用和开发依赖：

[project]
name = "your-app-name"
version = "0.1.0"
# 生产环境依赖：引用固定版本的requirements.txt
dependencies = [
    "-r requirements.txt"
]

[project.optional-dependencies]
# 开发环境依赖：未固定patch版本的顶层依赖，方便快速更新
dev = [
    "fastapi>=0.100.0",
    "uvicorn",
    "pytest>=7.0.0",
    # 根据你的项目需求添加其他开发依赖
]

2. 初始化requirements.txt #

开发初期，先安装开发依赖，再生成初始的固定依赖文件：

# 安装开发环境（包含未固定的顶层依赖）
pip install -e .[dev]
# 生成固定版本的requirements.txt，过滤本地冗余依赖
pip freeze --exclude-editable | grep -v "^pkg-resources" > requirements.txt

3. 日常开发流程 #

• 更新依赖：直接用pip install <package> --upgrade更新单个依赖，测试无误后重新执行上述freeze命令，锁定所有依赖版本
• 生产环境安装：直接执行pip install .，或pip install -r requirements.txt，确保依赖完全一致

注意事项 #

• 应用开发和库开发的核心区别：库需要兼容更广的依赖版本范围，而应用需要绝对的环境一致性，因此固定全量依赖版本是必要的
• 提交代码时，务必将pyproject.toml和requirements.txt都纳入版本控制

内容的提问来源于stack exchange，提问作者user430953