monorepo 与 multirepo 是 python 大规模项目两种主流代码仓库组织策略：前者通过单一仓库统一管理子项目，依赖根目录构建配置与工作区支持实现原子化变更；后者按功能拆分为独立仓库，各自治理版本、ci/cd 与发布流程。
在 Python 大规模项目中，如何组织代码仓库结构直接影响依赖管理、版本发布、CI/CD 效率及团队协作模式。Monorepo 与 Multirepo 是两种主流的代码仓库组织策略，各自具备不同的约束条件与适用场景。以下是针对该问题的分析与实践路径：
一、Monorepo 模式：单一仓库统一管理
Monorepo 将多个 Python 子项目（如核心库、CLI 工具、Web 服务、数据处理模块等）纳入同一 Git 仓库，共享统一的依赖声明、构建配置与版本控制历史。其核心优势在于跨组件依赖的一致性保障与原子化变更能力。
1、使用 pyproject.toml 在仓库根目录定义全局构建系统（如 Poetry 或 Hatch），并通过 [tool.poetry.workspace] 启用工作区支持，使各子包可被识别为可安装的本地依赖。
2、在各子包目录下放置独立的 pyproject.toml，声明自身元数据与依赖，但不包含 [build-system]，由根目录统一接管构建逻辑。
立即学习“Python免费学习笔记（深入）”；
3、通过 pip install -e ./subpkg-a 方式在开发环境中以可编辑模式安装子包，确保跨包调用时实时生效且无需重复发布。
二、Multirepo 模式：按功能边界拆分独立仓库
Multirepo 将不同职责的 Python 组件分别置于独立 Git 仓库中，每个仓库拥有完整的生命周期管理能力，包括独立 CI 流水线、语义化版本号与 PyPI 发布流程。该模式强调松耦合与自治性。
1、为每个仓库配置 setup.cfg 或 pyproject.toml，明确指定 project.version 并启用 setuptools-scm 实现基于 Git 标签的自动版本推导。
2、在依赖方仓库的 pyproject.toml 中，通过 [project.dependencies] 引用已发布的包，例如：my-core-lib = "^2.4.0"。
3、使用 pip-tools 管理锁定文件，在 requirements.in 中声明上游包名与最小兼容版本，运行 pip-compile requirements.in 生成确定性 requirements.txt。
三、依赖解析冲突的隔离处理
当项目同时引入多个第三方包且存在间接依赖版本不一致时，Monorepo 与 Multirepo 分别采用不同机制避免环境不可复现问题。
1、在 Monorepo 中，启用 poetry lock --no-update 锁定整个工作区的依赖图，并将 poetry.lock 提交至版本库，确保所有开发者与 CI 节点解析出完全一致的依赖树。
2、在 Multirepo 中，每个子仓库维护独立的 poetry.lock 或 requirements.txt，并通过 pip install --require-hashes 验证安装完整性，强制要求哈希值匹配。
3、对跨仓库强依赖场景，使用 pip install git+https://github.com/org/repo@v1.2.3#subdirectory=src/mylib 直接拉取特定提交的子目录内容，绕过 PyPI 发布环节。
四、CI/CD 流水线中的包可见性控制
持续集成阶段需准确识别哪些包因代码变更而需重新测试或发布，两种模式分别依赖不同的变更检测逻辑。
1、Monorepo 下采用 git diff --name-only HEAD~1 获取本次提交修改的文件路径，结合预设的目录映射规则（如 services/api/ → api-service）定位受影响组件。
2、Multirepo 下每个仓库默认触发全量流水线，但可通过 semantic-release 解析提交信息前缀（如 feat(api): add user endpoint）判断是否需要执行发布步骤。
3、在 Monorepo 的 CI 中，使用 tox -e py39 -- -k "test_user_flow" 对变更关联的测试用例进行精准筛选，跳过无关模块的测试执行。
