跨平台开发 / 系统课时

读懂 pubspec 版本约束

读懂 pubspec 版本约束

修改 Flutter 项目的 pubspec.yaml 时,版本号决定的并不只是“安装哪个版本”,而是 Pub 解析器允许选择哪些版本。本节从直接依赖、开发依赖和 SDK 约束入手,读懂常见版本范围,并理解它们与 pubspec.lock 的分工。

学习目标

  • 区分 dependencies、dev_dependencies 与 SDK 约束的职责
  • 读懂精确版本、范围约束和 caret 约束
  • 理解 pubspec.yaml 与 pubspec.lock 在依赖解析中的不同作用

先分清依赖放在哪里

Flutter 项目的依赖声明集中在 pubspec.yaml。业务代码运行时需要直接使用的包通常放入 dependencies;测试、lint、代码生成等只参与开发流程的工具放入 dev_dependencies;environment 则限定当前项目能够使用的 Dart SDK 范围。

yaml
environment:
  sdk: '>=3.3.0 <4.0.0'

dependencies:
  flutter:
    sdk: flutter
  collection: ^1.18.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^5.0.0

这里的 collection 是项目直接声明的普通依赖,flutter_lints 只服务于开发期静态检查。它们自身依赖的其他包属于传递依赖,由 Pub 解析器自动计算,不需要把所有传递依赖再次写入项目配置。

读懂常见版本约束

版本约束描述的是允许解析的集合,而不是一定会安装的唯一版本。常见写法如下。

写法 含义
1.2.3 只接受版本 1.2.3
^1.2.3 接受 >=1.2.3 <2.0.0
^0.2.3 接受 >=0.2.3 <0.3.0
^0.0.3 接受 >=0.0.3 <0.0.4
>=1.2.0 <2.0.0 显式指定最小和最大范围
any 不主动限制包版本,通常不建议用于长期维护的直接依赖

caret 写法适合表达“接受兼容版本”。当主版本大于零时,^1.2.3 可以升级到同一主版本中的较新版本;处于 0.x 阶段时范围会更严格,因为较小版本变化也可能包含不兼容修改。

SDK 约束同样参与解析。如果某个包要求更高版本的 Dart SDK,即使它自身的包版本满足范围,当前项目也可能无法选择该版本。因此排查依赖冲突时不能只看包版本号,还要同时检查 environment。

理解约束与锁定版本的分工

pubspec.yaml 表达的是项目允许哪些版本,Pub 解析器会在所有 SDK 和包约束能够同时成立的前提下选择具体版本。解析成功后,应用项目的 pubspec.lock 会记录本次选择的精确版本,使团队成员和 CI 更容易得到一致的依赖集合。

例如 collection: ^1.18.0 并不意味着每次执行依赖解析都必须固定使用 1.18.0;真正已经解析出的具体版本可以在锁文件中查看。对于 Flutter 应用,通常应将 pubspec.lock 纳入版本控制;可发布的库或 package 则主要依靠 pubspec.yaml 向使用者表达兼容范围。

修改约束后立即验证

调整版本范围后,应立即执行依赖解析,而不是等到编译阶段才发现冲突。下面的命令在解析成功时只输出一个确定的标记,便于确认命令退出状态。

bash
flutter pub get >/dev/null && echo 'pub-get: ok'

预期输出

text
pub-get: ok

如果约束无法同时满足,flutter pub get 会返回非零退出码,并在错误信息中说明参与冲突的依赖关系。此时应先找出发生冲突的直接依赖、SDK 范围或上游版本要求,而不是把所有依赖统一改成更宽的范围。

版本约束的目标不是追求“越宽越好”或“越死越安全”,而是在允许兼容升级与避免意外破坏之间建立明确边界。能够区分约束范围和锁定结果后,依赖升级、CI 重现和冲突定位都会更可控。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

读懂 pubspec 版本约束

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通