Pub 依赖管理 #

依赖管理概述 #

依赖管理是 Pub 的核心功能之一，它涉及：

声明依赖：在 pubspec.yaml 中定义项目需要的包
版本约束：指定可接受的版本范围
依赖解析：Pub 自动解析并下载满足约束的版本
冲突解决：处理版本冲突和兼容性问题

版本约束 #

语义化版本（SemVer） #

Dart 包遵循语义化版本规范：MAJOR.MINOR.PATCH

text

1.2.3
│ │ │
│ │ └── PATCH：向后兼容的 bug 修复
│ └──── MINOR：向后兼容的功能新增
└────── MAJOR：不兼容的 API 变更

版本约束语法 #

1. 精确版本 #

yaml

dependencies:
  my_package: 1.2.3

锁定到特定版本，不推荐用于库包。

2. 范围约束 #

yaml

dependencies:
  my_package: '>=1.0.0 <2.0.0'
  my_package: '>=1.0.0'        # 大于等于
  my_package: '<2.0.0'         # 小于
  my_package: '>1.0.0'         # 大于
  my_package: '<=2.0.0'        # 小于等于

3. 兼容版本（^） #

yaml

dependencies:
  my_package: ^1.2.3

等价于 >=1.2.3 <2.0.0

text

^1.2.3  →  >=1.2.3 <2.0.0
^0.1.2  →  >=0.1.2 <0.2.0
^0.0.3  →  >=0.0.3 <0.0.4

4. 补丁版本（~） #

yaml

dependencies:
  my_package: ~1.2.3

等价于 >=1.2.3 <1.3.0

text

~1.2.3  →  >=1.2.3 <1.3.0
~1.2    →  >=1.2.0 <1.3.0
~1      →  >=1.0.0 <2.0.0

5. 任意版本 #

yaml

dependencies:
  my_package: any

不推荐使用，可能导致不可预测的行为。

版本约束对比 #

约束	范围	推荐场景
`^1.2.3`	`>=1.2.3 <2.0.0`	库包（推荐）
`~1.2.3`	`>=1.2.3 <1.3.0`	需要精确控制补丁版本
`>=1.0.0 <2.0.0`	自定义范围	有特殊版本要求
`1.2.3`	精确版本	应用项目（可选）
`any`	任意版本	不推荐

依赖来源 #

1. pub.dev（默认） #

从官方仓库获取：

yaml

dependencies:
  http: ^1.0.0

2. Git 仓库 #

从 Git 仓库获取：

基本用法 #

yaml

dependencies:
  my_package:
    git:
      url: https://github.com/user/repo.git

指定分支/标签/提交 #

yaml

dependencies:
  my_package:
    git:
      url: https://github.com/user/repo.git
      ref: main          # 分支
      # ref: v1.0.0      # 标签
      # ref: abc123      # 提交哈希

指定路径 #

yaml

dependencies:
  my_package:
    git:
      url: https://github.com/user/repo.git
      path: packages/my_package

SSH 方式 #

yaml

dependencies:
  my_package:
    git:
      url: git@github.com:user/repo.git

3. 本地路径 #

使用本地包：

yaml

dependencies:
  my_package:
    path: ../my_package

相对路径 #

yaml

dependencies:
  my_package:
    path: ./packages/my_package

绝对路径 #

yaml

dependencies:
  my_package:
    path: /Users/user/projects/my_package

4. 私有仓库 #

使用私有包仓库：

yaml

dependencies:
  my_private_package:
    hosted:
      name: my_private_package
      url: https://my-private-repo.com
    version: ^1.0.0

简写形式 #

yaml

dependencies:
  my_private_package:
    hosted: https://my-private-repo.com
    version: ^1.0.0

依赖类型 #

dependencies - 生产依赖 #

运行时必需的依赖：

yaml

dependencies:
  http: ^1.0.0
  path: ^1.8.0

dev_dependencies - 开发依赖 #

仅在开发和测试时需要的依赖：

yaml

dev_dependencies:
  test: ^1.24.0
  lints: ^2.0.0
  build_runner: ^2.4.0

开发依赖不会传递给依赖此包的其他项目。

dependency_overrides - 依赖覆盖 #

强制使用特定版本：

yaml

dependency_overrides:
  http: 1.1.0
  path: 1.9.0

覆盖 Git 依赖 #

yaml

dependency_overrides:
  my_package:
    git:
      url: https://github.com/user/repo.git
      ref: fix-branch

覆盖本地依赖 #

yaml

dependency_overrides:
  my_package:
    path: ../my_local_package

依赖解析 #

解析流程 #

text

┌─────────────────────────────────────────────────────────────┐
│                     依赖解析流程                             │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. 读取 pubspec.yaml                                        │
│     │                                                        │
│     ▼                                                        │
│  2. 收集所有依赖约束                                          │
│     │                                                        │
│     ▼                                                        │
│  3. 检查 pubspec.lock                                        │
│     │                                                        │
│     ├── 存在且兼容 ──► 使用锁定版本                           │
│     │                                                        │
│     └── 不存在或不兼容                                        │
│          │                                                   │
│          ▼                                                   │
│  4. 解析依赖树                                                │
│     │                                                        │
│     ▼                                                        │
│  5. 检查版本约束冲突                                          │
│     │                                                        │
│     ├── 有冲突 ──► 报错                                       │
│     │                                                        │
│     └── 无冲突                                                │
│          │                                                   │
│          ▼                                                   │
│  6. 下载依赖                                                  │
│     │                                                        │
│     ▼                                                        │
│  7. 生成 pubspec.lock                                        │
│                                                              │
└─────────────────────────────────────────────────────────────┘

传递依赖 #

当包 A 依赖包 B，包 B 依赖包 C 时：

text

my_app (你的项目)
  └── http (直接依赖)
        ├── http_parser (传递依赖)
        ├── meta (传递依赖)
        └── path (传递依赖)

查看依赖树 #

bash

# 查看完整依赖树
dart pub deps

# 紧凑格式
dart pub deps --style=compact

# 仅显示直接依赖
dart pub deps --no-dev

版本冲突解决 #

常见冲突场景 #

1. 版本范围不兼容 #

yaml

# 项目 A
dependencies:
  http: ^1.0.0

# 项目 A 依赖的包 B
dependencies:
  http: ^2.0.0  # 冲突！

2. SDK 版本不兼容 #

yaml

# 包 A
environment:
  sdk: '>=2.0.0 <3.0.0'

# 包 B
environment:
  sdk: '>=3.0.0 <4.0.0'  # 冲突！

解决方案 #

1. 更新版本约束 #

yaml

# 放宽版本约束
dependencies:
  http: '>=1.0.0 <3.0.0'

2. 使用 dependency_overrides #

yaml

dependency_overrides:
  http: ^1.1.0

3. 更新依赖 #

bash

# 升级依赖到兼容版本
dart pub upgrade

# 强制升级主要版本
dart pub upgrade --major-versions

4. 联系包作者 #

如果冲突无法解决，可以联系包作者请求更新。

依赖更新策略 #

检查更新 #

bash

# 检查过时的依赖
dart pub outdated

输出示例：

text

Dependencies         Current  Upgradable  Resolvable  Latest

direct dependencies:
http                 1.0.0    1.1.0      1.2.0      1.2.0
path                 1.8.0    1.8.3      1.9.0      1.9.0

dev_dependencies:
test                 1.24.0   1.24.0     1.24.0     1.25.0

更新依赖 #

bash

# 更新到兼容的最新版本
dart pub upgrade

# 更新特定包
dart pub upgrade http

# 强制更新到最新版本
dart pub upgrade --major-versions

更新流程 #

text

1. 检查更新
   dart pub outdated

2. 测试更新
   dart pub upgrade http --dry-run

3. 执行更新
   dart pub upgrade http

4. 运行测试
   dart test

5. 提交变更
   git add pubspec.lock
   git commit -m "Update http to 1.1.0"

依赖安全 #

安全审计 #

bash

# 检查已知漏洞
dart pub outdated

安全最佳实践 #

使用精确版本约束

yaml

# ✅ 推荐
dependencies:
  http: ^1.0.0

# ❌ 不推荐
dependencies:
  http: any

定期更新依赖

bash

# 每周或每月检查更新
dart pub outdated
dart pub upgrade

审查新依赖

添加新依赖前：

检查 pub.dev 上的评分
查看依赖树
检查许可证

bash

# 查看依赖树
dart pub deps

# 查看包信息
dart pub cache dir

锁定依赖版本

对于应用项目，始终提交 pubspec.lock。

私有仓库配置 #

搭建私有仓库 #

使用 unpub #

bash

# 安装 unpub
dart pub global activate unpub

# 启动服务
unpub --database mongodb://localhost:27017/dart_pub

使用 pub_server #

bash

# 安装 pub_server
dart pub global activate pub_server

# 启动服务
pub_server --port 8080

配置私有仓库 #

yaml

# pubspec.yaml
dependencies:
  my_private_package:
    hosted:
      name: my_private_package
      url: https://my-private-repo.com
    version: ^1.0.0

认证配置 #

bash

# 添加认证令牌
dart pub token add https://my-private-repo.com

# 输入令牌
# Enter secret token: your-secret-token

# 查看令牌
dart pub token list

# 删除令牌
dart pub token remove https://my-private-repo.com

依赖管理最佳实践 #

1. 明确区分依赖类型 #

yaml

# 生产依赖
dependencies:
  http: ^1.0.0

# 开发依赖
dev_dependencies:
  test: ^1.24.0
  lints: ^2.0.0

2. 使用兼容版本约束 #

yaml

# ✅ 推荐
dependencies:
  http: ^1.0.0

# ❌ 不推荐
dependencies:
  http: any

3. 定期检查更新 #

bash

# 每周运行
dart pub outdated

4. 提交 pubspec.lock #

bash

# 应用项目
git add pubspec.lock

# 库项目（可选）
# 提交可以确保 CI 使用相同版本

5. 使用 dart pub add 而非手动编辑 #

bash

# ✅ 推荐
dart pub add http

# ❌ 不推荐
# 手动编辑 pubspec.yaml

6. 避免循环依赖 #

text

# 循环依赖
A → B → A  ❌

# 解决方案：提取公共部分
A → C
B → C

7. 控制依赖数量 #

bash

# 查看依赖数量
dart pub deps --style=compact | wc -l

8. 使用本地依赖进行开发 #

yaml

# 开发时使用本地包
dependency_overrides:
  my_package:
    path: ../my_package

常见问题 #

1. 依赖解析失败 #

bash

# 错误信息
Because my_app depends on http ^1.0.0 which doesn't match any versions, version solving failed.

# 解决方案
# 检查版本是否存在
dart pub outdated

# 更新版本约束
dart pub add http:^1.1.0

2. Git 依赖问题 #

bash

# 错误信息
Git error. Command: git clone

# 解决方案
# 检查 Git 是否安装
git --version

# 检查网络连接
# 使用镜像或代理

3. 缓存问题 #

bash

# 清理缓存
dart pub cache clean

# 重新获取
dart pub get

4. 版本冲突 #

bash

# 查看冲突详情
dart pub get --verbose

# 使用依赖覆盖
dependency_overrides:
  conflicting_package: ^2.0.0

依赖管理工具对比 #

功能	Pub	npm	pip
锁定文件	✅ pubspec.lock	✅ package-lock.json	❌
语义化版本	✅	✅	⚠️
Git 依赖	✅	✅	✅
本地依赖	✅	✅	✅
私有仓库	✅	✅	✅
依赖覆盖	✅	✅	❌

下一步 #

现在你已经掌握了依赖管理，接下来学习发布包将你的包分享给全世界！