跨平台开发 / 系统课时

管理 pubspec 与第三方包

管理 pubspec 与第三方包

第三方包能否稳定使用,取决于 pubspec.yaml 中的约束、Pub 的解析结果以及锁文件是否被正确管理。本篇从一个最小项目出发,分别添加运行时依赖与开发依赖,再用命令检查最终解析结果和可复现边界。

学习目标

  • 读懂 environment、dependencies 与 dev_dependencies 的职责。
  • 使用 dart pub add、dart pub get 和 dart pub deps 管理并检查依赖。
  • 理解 pubspec.lock 与 .dart_tool/package_config.json 在依赖解析中的作用。

先读懂 pubspec 的约束

pubspec.yaml 位于包根目录。下面是一个可用于练习的配置片段,其中 SDK 下界保证示例依赖所需的语言和工具能力:

yaml
name: dependency_lab
publish_to: none

environment:
  sdk: ">=3.8.0 <4.0.0"

dependencies:
  path: ^1.9.1

dev_dependencies:
  lints: ^6.1.0

environment.sdk 限制可运行这个包的 Dart SDK 范围。dependencies 放程序运行或库公开功能真正需要的包;dev_dependencies 放分析、测试、代码生成等只服务于开发过程的工具。

例如,业务代码若导入 package:path/path.dart,path 就应位于 dependencies。只用于静态检查规则的 lints 不应成为使用者运行程序时的传递需求,因此放在 dev_dependencies。

用 dart pub 修改并解析依赖

手工编辑 YAML 没有问题,但新增依赖时可以让 Pub 同时修改配置并执行解析。若从只含 name 与 environment 的项目开始,可执行:

bash
dart pub add path:^1.9.1

预期输出会包含依赖解析和变更提示:

text
Resolving dependencies...
+ path 1.9.1
Changed 1 dependency!

再添加仅开发期使用的 lint 包:

bash
dart pub add dev:lints:^6.1.0

预期输出的核心信息类似:

text
Resolving dependencies...
+ lints 6.1.0
Changed 1 dependency!

下载提示和耗时可能因缓存与网络环境不同。若 pubspec.yaml 已经写好,直接执行 dart pub get 即可根据现有约束获取依赖:

bash
dart pub get

预期结果是解析成功,并在项目中生成或更新 pubspec.lock 与 .dart_tool/package_config.json。控制台通常以依赖获取成功结束,具体下载行会随本机缓存状态变化。

Pub 从约束到锁定依赖的解析流程

检查最终解析了什么

pubspec.yaml 写的是允许范围,真正被选中的直接依赖和传递依赖可以用 dart pub deps 查看。为了避免默认树形输出过长,这里使用列表样式:

bash
dart pub deps --style=list

预期结果至少会列出当前包以及已经解析的 path、lints;如果这些包还有传递依赖,也会一并出现:

text
dependency_lab
...
lints 6.1.0
path 1.9.1

省略号表示不同 SDK 与依赖组合下可能出现的其他已解析包。排查“为什么项目里出现某个没有直接声明的包”时,改用默认的树形输出通常更容易追踪它来自哪条依赖链。

dart pub get 解析成功后,.dart_tool/package_config.json 会告诉 Dart 工具链每个 package: URI 应映射到哪里。这个文件由工具生成,不应手工编辑;需要重新生成时再次运行 Pub 命令。

用锁文件建立可复现基础

pubspec.lock 记录当前解析到的具体版本。对于可运行的应用项目,应把锁文件提交到版本控制,让团队和部署环境使用同一组依赖版本;对于准备发布给其他项目使用的普通库包,通常不提交锁文件,而是持续验证声明的版本范围是否兼容。

在应用的 CI 或部署阶段,如果要求严格使用已经审核过的锁定结果,可以执行:

bash
dart pub get --enforce-lockfile

当 pubspec.yaml 与锁文件一致且锁定内容可用时,预期结果是依赖解析成功,不会擅自改写为另一组版本。若二者无法严格对应,该命令会失败并要求先显式更新锁文件,而不是静默选择新版本。

处理最常见的解析失败

当 Pub 报版本求解失败时,先检查 SDK 约束,再检查直接依赖之间是否要求互不兼容的版本区间。不要第一时间使用过宽的版本约束或长期保留 dependency_overrides,因为它们可能把真实兼容性问题推迟到运行阶段。

先用当前配置重新解析并读取报错中的冲突链,再决定是升级 SDK、调整某个直接依赖的范围,还是替换不再兼容的包。完成修改后再次运行 dart pub get 和 dart pub deps,确认“声明的范围、锁定的具体版本、实际依赖图”三者一致,项目的依赖基础才算真正可复现。

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

目录与阅读设置

阅读设置

17

记录一个想法

管理 pubspec 与第三方包

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

登录哪都通