从GitHub到PyPI：ddddocr项目发布全流程

2026-02-04 05:25:38作者：廉皓灿Ida

引言：验证码识别工具的发布密码

你是否曾为开源项目发布流程中的依赖管理、打包配置、版本控制而头疼？作为开发者，将本地项目转化为全球用户可通过pip install一键安装的PyPI包，需要跨越代码提交、环境配置、打包测试等多重障碍。本文以验证码识别领域的明星项目ddddocr（带带弟弟OCR）为例，系统拆解从GitHub代码管理到PyPI发布的全流程，包含10+关键配置文件解析、5大常见错误解决方案和3种自动化发布策略，助你掌握Python开源项目的标准化发布方法。

一、项目结构与核心配置解析

1.1 目录结构设计

ddddocr采用典型的Python项目结构，核心代码与资源文件分离，确保打包时的完整性：

ddddocr/
├── __init__.py           # 包初始化文件
├── __main__.py           # 命令行入口
├── common.onnx           # 核心模型文件
├── common_det.onnx       # 检测模型文件
├── core/                 # 核心算法模块
│   ├── ocr_engine.py     # OCR识别引擎
│   └── detection_engine.py # 目标检测引擎
├── api/                  # API服务模块
└── utils/                # 工具函数集

1.2 setup.py核心配置

作为项目打包的核心配置文件，setup.py定义了包的元数据、依赖关系和安装规则：

from setuptools import setup, find_packages

with open("README.md", "r", encoding="utf-8") as fh:
    long_description = fh.read()

setup(
    name="ddddocr",  # PyPI包名
    version="1.6.0",  # 语义化版本号
    author="sml2h3",
    description="带带弟弟OCR",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/sml2h3/ddddocr",  # 项目主页
    packages=find_packages(),  # 自动发现包
    classifiers=[  # 分类信息，影响PyPI搜索结果
        "Programming Language :: Python :: 3.7",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    install_requires=[  # 核心依赖
        'numpy', 'onnxruntime', 'Pillow', 'opencv-python-headless'
    ],
    extras_require={  # 可选依赖
        'api': ['fastapi>=0.100.0', 'uvicorn[standard]>=0.20.0']
    },
    entry_points={  # 命令行入口配置
        'console_scripts': [
            'ddddocr=ddddocr.__main__:main',
        ],
    },
)

1.3 MANIFEST.in资源文件管理

对于模型文件等非Python资源，需通过MANIFEST.in指定打包规则：

recursive-include ddddocr common.onnx
recursive-include ddddocr common_old.onnx
recursive-include ddddocr common_det.onnx

这条配置确保三个ONNX模型文件被正确打包，避免用户安装后出现"模型文件缺失"错误。

1.4 requirements.txt依赖管理

项目根目录的requirements.txt定义了开发环境依赖：

onnxruntime
onnx
Pillow
numpy<2.0.0
opencv-python==3.4.16.59
fastapi>=0.100.0
uvicorn[standard]>=0.20.0
pydantic>=2.0.0

注意版本限制策略：numpy<2.0.0采用上限限制避免不兼容更新，opencv-python==3.4.16.59使用精确版本确保算法稳定性。

二、从代码提交到PyPI发布的流程设计

2.1 版本控制与提交规范

采用语义化版本（Semantic Versioning）管理版本号：

MAJOR（主版本）：不兼容的API变更（1.0.0 → 2.0.0）
MINOR（次版本）：向后兼容的功能新增（1.5.0 → 1.6.0）
PATCH（修订版）：向后兼容的问题修复（1.6.0 → 1.6.1）

提交信息遵循Angular规范：

<type>(<scope>): <subject>

<body>

<footer>

常见type包括：feat(新功能)、fix(修复)、docs(文档)、style(格式)、refactor(重构)。

2.2 本地打包与测试

2.2.1 构建源码分发包

python setup.py sdist

生成.tar.gz格式的源码包，位于dist/目录下。

2.2.2 构建wheel包

python setup.py bdist_wheel

生成.whl格式的二进制包，支持更快的安装速度。

2.2.3 本地安装测试

pip install dist/ddddocr-1.6.0-py3-none-any.whl

测试包括：

命令行调用：ddddocr --version验证入口正确性
API功能测试：import ddddocr; ocr = ddddocr.DdddOcr(); ocr.classification(open("test.png", "rb").read())
依赖完整性检查：pip show ddddocr确认依赖是否正确安装

2.3 PyPI发布步骤

2.3.1 账号准备

在PyPI注册账号
创建API token（推荐）或获取用户名密码

2.3.2 安装发布工具

pip install twine setuptools wheel

2.3.3 上传包到PyPI

twine upload dist/*

输入API token（用户名留空，密码输入token）完成上传。

2.4 发布流程自动化（GitHub Actions）

创建.github/workflows/publish.yml实现自动发布：

name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  build-and-publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install setuptools wheel twine
      - name: Build
        run: python setup.py sdist bdist_wheel
      - name: Publish
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          user: __token__
          password: ${{ secrets.PYPI_API_TOKEN }}

工作流触发条件：当GitHub Release被发布时自动执行，从secrets获取PyPI API token完成发布。

三、常见问题解决方案与最佳实践

3.1 资源文件打包问题

症状：安装后提示FileNotFoundError: common.onnx
原因：MANIFEST.in配置错误或未设置include_package_data=True
解决方案：

确认setup.py中包含：

include_package_data=True,
install_package_data=True,

MANIFEST.in使用绝对路径或正确的相对路径

3.2 依赖冲突处理

案例：numpy 2.0.0发布后导致安装失败
预防方案：在setup.py中设置版本上限：

install_requires=['numpy<2.0.0', ...]

解决流程：

flowchart TD
    A[用户报告ImportError] --> B[本地复现问题]
    B --> C[确认冲突依赖版本]
    C --> D[修改setup.py限制版本]
    D --> E[发布新版本]
    E --> F[通知用户升级]

3.3 跨平台兼容性

确保在不同操作系统上的兼容性：

使用Operating System :: OS Independent分类
避免依赖系统级库，优先使用纯Python实现或二进制wheel
图像相关操作使用Pillow而非系统自带的图像处理库

四、项目维护与迭代策略

4.1 版本迭代计划

采用"主版本+长期支持版"并行策略：

主版本（Main Line）：每季度发布，包含新功能
长期支持版（LTS）：每年发布一个，支持18个月安全更新

版本路线图示例：

timeline
    title ddddocr版本规划
    2024 Q1 : 1.6.0 (LTS) - 基础OCR功能
    2024 Q2 : 1.7.0 - 新增滑动验证码支持
    2024 Q3 : 1.8.0 - 提升小字符识别率
    2025 Q1 : 2.0.0 (LTS) - API重构，性能优化

4.2 用户反馈处理机制

建立三级反馈处理流程：

问题确认：通过python -m ddddocr.check收集环境信息
优先级分类：P0（阻断性）、P1（功能异常）、P2（性能优化）
修复发布：P0问题24小时内发布hotfix，P1问题纳入下一迭代

五、总结与展望

本文系统讲解了ddddocr项目从GitHub到PyPI的完整发布流程，涵盖：

核心配置文件解析（setup.py/MANIFEST.in/requirements.txt）
标准化发布流程设计（版本控制→本地测试→PyPI上传）
自动化部署实现（GitHub Actions配置）
常见问题解决方案（资源打包/依赖冲突/跨平台兼容）

随着验证码技术的发展，ddddocr将持续迭代模型优化和功能扩展。未来版本计划引入：

多语言识别支持
模型轻量化方案
实时推理性能优化

掌握本文所述的发布流程和最佳实践，不仅能提升项目发布效率，更能显著降低用户使用门槛，让优秀的开源项目获得更广泛的应用。

附录：实用命令速查表

操作	命令
本地安装	`pip install -e .`
构建包	`python setup.py sdist bdist_wheel`
测试上传	`twine upload --repository-url https://test.pypi.org/legacy/ dist/*`
检查依赖冲突	`pip check ddddocr`
生成依赖清单	`pip freeze > requirements.txt`