迁移现有 Python 项目到 pyproject.toml 完整指南

为什么建议迁移到 pyproject.toml？

pyproject.toml 遵循 PEP 518 标准，具备以下核心优势：

• 标准化统一：元数据、依赖声明与构建后端配置收敛于单一文件，主流工具链（如 build、pytest、mypy）均已原生支持。
• 语法简洁直观：采用 TOML 格式替代动态执行的 .py 脚本，避免运行时代码注入风险，配置可读性与版本控制友好度显著提升。
• 灵活可扩展：支持自定义构建后端插件，可无缝适配不同项目对打包、测试或文档生成的差异化需求。

准备条件与安装

迁移前请确保当前环境具备基础 Python 支持，并备份原有工程文件。推荐使用 uv 作为核心操作工具，其底层为 Rust 编写，执行效率显著优于传统 pip。uv 可通过 pip 直接安装：

pip install uv

第1步：使用 uv 初始化项目结构

此步骤旨在在项目根目录生成规范的 pyproject.toml 骨架。进入目标项目文件夹后，执行初始化命令：

uv init --project .

目的：自动生成包含基础版本、名称与构建系统的配置文件。
重要参数：--project . 表示在当前目录下就地创建，若目录已存在同名文件，uv 默认会追加而非强制覆盖，但为确保安全，强烈建议在操作前手动复制一份 setup.py 与 requirements.txt 至独立备份目录。

第2步：导入现有依赖关系

迁移的核心在于将历史依赖准确转入新配置。若项目原本使用 requirements.txt，可直接映射：uv add -r requirements.txt

uv add -r requirements.txt

入口与动作：在终端运行上述命令。uv 会解析原文件的每行内容，自动去重、锁定版本号，并将结果写入 [project.dependencies] 区块。对于未使用文本依赖表的项目，可逐条添加：uv add package_name。uv 同步生成 uv.lock 锁文件以保证多环境一致性。

第3步：核验配置与清理旧文件

完成判断：运行 uv sync 检查虚拟环境能否正常拉起。若导入无报错，且在代码中调用第三方库能正常运行，则迁移成功。
风险提醒：确认 pyproject.toml 语法无误且依赖全部生效后，方可删除旧的 setup.py、setup.cfg 及 requirements.txt。切勿在未验证构建链路的阶段提前移除源文件，以免破坏 CI/CD 流水线或线上部署脚本。

pyproject.toml 核心字段说明

生成的配置文件主要包含以下模块：

• [project]：定义项目名称、版本、作者、摘要、许可证及运行时依赖（dependencies）。
• [project.optional-dependencies]：声明 dev、test、docs 等场景所需的扩展包。
• [build-system]：指定构建工具链（如 setuptools 或 hatchling），保证异地克隆项目时可正确执行 pip install .。
• [tool.*]：预留空间供各插件配置，例如 [tool.pytest.ini_options] 或 [tool.ruff]。

总结

通过 uv 的一键映射功能，绝大多数传统 Python 项目均可在数分钟内完成向 pyproject.toml 的结构化过渡。规范化的配置不仅降低了维护成本，也为后续接入容器化部署、自动化测试提供了稳定基底。

以上就是将现有 Python 项目迁移至 pyproject.toml 并配合 uv 管理的详细内容，更多关于 Python 项目配置优化与包管理实践的资料请关注本站其它相关文章！