Sunqy 文档库

主题

43 · 多包工程与 Melos（Monorepo） ​

一句话定位：当"App + 组件库 + 若干内部包"要一起维护时，单仓库多包（Monorepo）是 Flutter 的标准解法，工具是 Melos（或 pub workspace）。对应前端的 pnpm workspace / Turborepo / Nx。

开篇速览 ​

问题答案
前端对应物pnpm workspace / Turborepo / Lerna / Nx
核心概念一个仓库多个 Dart 包；melos bootstrap 管理依赖；melos run 批量命令
适合谁App + 组件库 + 业务包一起发版、共享代码的团队
一句话红线只有"多个包确实需要同步演进"才上 Monorepo；单个 App 硬拆多包只会增加构建与发布成本

代码来源说明：HaierEnergy 当前是单包工程（lib/ 内含 he_components/ 目录而非独立包，见 07 篇）。 组件库抽离方案见 30 篇，本篇讲抽离之后的工程组织。

一、什么时候需要多包 ​

形态适用
单包：所有代码在一个 lib/中小型 App，起步默认
独立包发布到 pub组件库要对外复用（30 篇）
Melos Monorepo内部多个包要一起演进、一起发版，不想每个都推 pub
微前端式多 App多个独立 App 共享代码（更大规模才考虑）

二、Melos 是什么 ​

Melos 是 Dart 生态的 Monorepo 管理工具：

能力前端对照作用
工作区定义pnpm-workspace.yaml声明哪些目录是包
melos bootstrappnpm install链接本地包依赖
melos runTurborepo/Nx 命令编排按依赖序批量跑脚本
版本与发版changesets统一版本号 + 自动生成 changelog

三、目录与配置 ​

repo/
├── melos.yaml          # 工作区定义
├── apps/
│   └── haierenergy/    # App 包
└── packages/
    ├── he_components/  # 组件库
    └── he_network/     # 网络层
yaml
# melos.yaml
name: haierenergy
packages:
  - apps/**
  - packages/**

本地依赖用 path: 指向：

yaml
dependencies:
  he_components:
    path: ../../packages/he_components

四、常用命令与 CI ​

bash
fvm melos bootstrap        # 安装并链接所有包
fvm melos run analyze      # 对所有包跑 analyze
fvm melos run test         # 对所有包跑测试
fvm melos exec -- fvm flutter test   # 任意命令批量执行

CI 加速关键：

  • 缓存 melos bootstrap 的产物与 pub 缓存；
  • 只跑变更相关包的测试（melos run --scope），别全量；
  • 生成 .dart_tool / 依赖锁定要提交与否按团队约定。

五、版本策略 ​

策略适用工具
固定版本（所有包同号）内部组件库 + App 强耦合Melos 版本管理 / 手工统一
独立版本对外发布的包每个包独立 semver
按变更自动 bump大团队melos version 交互式 / changesets

六、什么时候不要用 ​

  • 只有一个 App，且没有明确复用诉求 → 别拆；
  • 团队没有 CI 与发版规范 → 先理顺再上；
  • 组件库要对外发布 → 用独立 pub 包 + 仓库分域，不必强行 Monorepo；
  • 依赖图复杂、各包独立演进 → 独立仓库更清晰。

动手练习 ​

  1. 搭一个最小 Melos 工作区（一个 App + 一个组件包），本地 path 依赖跑通；
  2. 用 melos run 给两个包各加一条 analyze/test 脚本，验证按依赖序执行；
  3. 写一段"该不该上 Monorepo"的决策清单（含你项目的现状判断）。

自检清单 ​

  • [ ] 能说清 Monorepo 与独立 pub 包的边界
  • [ ] 会用 melos.yaml 声明工作区并用 melos bootstrap 链接
  • [ ] 会用 melos run 批量执行 analyze/test
  • [ ] 知道 CI 里如何缓存与按变更范围跑测试
  • [ ] 能判断"什么时候不该上 Monorepo"

常见误区 ​

  • "Monorepo 就是多建几个目录"：没有 melos 链接与统一命令，就只是多个独立项目堆一起；
  • "拆了包就解耦了"：依赖关系没理清，拆包只是把混乱分散；
  • "所有包强制同步版本"：对外发布的包要独立 semver，强耦合才用固定版本；
  • "小项目也上 Melos"：单 App 拆多包会显著增加构建与维护成本。

相关文档 ​