RapidOCR打包演进之路：从setup.py到pyproject.toml的实践探索

在Python项目开发中，打包系统的选择直接影响着项目的可维护性和用户体验。对于像RapidOCR这样的开源项目而言，如何实现自动化版本号管理、简化下游构建流程，是持续迭代过程中必须面对的重要课题。本文将分享RapidOCR从传统setup.py迁移到pyproject.toml的完整实践过程，探讨新方案如何优雅地解决过往的痛点。

传统打包方式的核心挑战

## 传统打包方式的核心挑战

pyproject.toml方案的技术优势

回顾RapidOCR的打包演进历程，自项目发布wheel包以来，一直采用setuptools进行打包管理。在这一过程中，自动化版本号成为打包系统的核心需求——即根据Git标签自动生成版本号，而非手动维护。 为实现这一目标，早期方案通过GitHub Actions在打标签时获取tag信息，并传递给setuptools来完成版本号的自动化注入。这种方案虽然在一定程度上满足了需求，但也暴露出明显的局限性：当下游用户希望自行构建wheel包时，需要完整复制CI流程中的复杂步骤，理解其中各个环节的关联逻辑，这无疑增加了使用门槛和理解成本。同时，setup.py文件中耦合了大量业务逻辑，使得打包这一步变得异常复杂。

新打包方案的核心实现

基于pyproject.toml的打包方案带来了显著的改进。通过引入setuptools-scm库，可以直接从Git标签自动提取版本号，完全告别了手动维护版本的繁琐流程。配置文件形式的声明让打包逻辑更加清晰，也便于版本管理。 新方案成功解决了此前需要将rapidocr目录包裹一层才能正确导入的问题，使得项目结构更加合理。更重要的是，模型下载等辅助流程可以被清晰地分离出去，不再与打包核心逻辑混在一起。通过tools/prepare_wheel_assets.py脚本，模型资产的准备过程变得独立可控。

总结与展望

## 下游构建的简化实践

如有侵权，请联系删除。