pub：核心概念，Dart包管理器和pubspec.yaml

pubspec.yaml 结构

pubspec.yaml 文件是每个 Dart 或 Flutter 项目的核心配置文件。它采用 YAML 格式编写，包含元数据、依赖、构建配置和 SDK 约束。以下是 Flutter 应用程序的典型示例：

name: my_app
description: Flutter 应用示例
version: 1.0.0+1
publish_to: none

environment:
  sdk: ">=3.0.0 <4.0.0"
  flutter: ">=3.10.0"

dependencies:
  flutter:
    sdk: flutter
  http: ^1.1.0
  provider: ^6.0.5
  shared_preferences: ^2.2.0
  path_provider: ^2.1.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.0
  mockito: ^5.4.3

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    - assets/fonts/

pubspec.yaml 的关键字段：name — 包的唯一名称（仅限拉丁字母、下划线、数字）；description — 简短描述（发布时必须）；version — 语义化版本，加号后可选构建编号；environment — Dart SDK 和 Flutter SDK 的最低版本；dependencies — 应用程序的主要依赖；dev_dependencies — 仅用于开发和测试的依赖；flutter — Flutter 配置部分（assets、fonts、plugins）。

publish_to 字段控制发布的可用性：值为 none 禁止发布（通常用于应用程序），默认值为 https://pub.dev。dependency_overrides 字段允许在冲突情况下强制覆盖包的版本 — 谨慎使用，仅作为临时解决方案。

依赖及其类型

pub 支持四种类型的依赖，每种在 pubspec.yaml 中有自己的语法：

托管依赖（hosted）

标准类型 — 包从 pub.dev 或其他兼容注册中心下载。指定包名和版本。示例：http: ^1.1.0 将根据 caret 版本控制规则从 >=1.1.0 和 <2.0.0 范围内下载最新的兼容版本。

SDK 依赖

用于连接 Flutter SDK 或 Dart SDK。语法：flutter: sdk: flutter。包来自本地安装的 Flutter SDK，而非注册中心。SDK 依赖没有版本号 — 其版本由当前安装的 Flutter 版本决定。

路径依赖（path）

指向包含包的本地目录。在开发库和测试而不发布时很有用。语法：

dependencies:
  my_local_lib:
    path: ../my_local_lib

路径依赖不会记录在 pubspec.lock 中 — 每次更新都会从指定路径重新解析。

Git 依赖

允许直接从 git 仓库连接包。支持分支、标签和提交：

dependencies:
  my_git_lib:
    git:
      url: https://github.com/user/my_git_lib.git
      ref: main

Git 依赖适用于 fork、未发布的修复或处理 Pull Request。建议指定具体的标签或提交而不是分支，以避免构建时出现意外更改。

版本控制与范围

pub 严格遵守语义化版本控制 2.0：格式为 MAJOR.MINOR.PATCH，其中 MAJOR — 不兼容更改，MINOR — 向后兼容的新功能，PATCH — 向后兼容的修复。基于此方案，pub 确定包的兼容性并解决冲突。

在 pubspec.yaml 中使用三个主要运算符指定版本：

• Caret (^) — ^1.2.3 等同于 >=1.2.3 且 <2.0.0。最常用的运算符，因为它假定在主版本范围内兼容。对于主版本为 0 的包 — ^0.1.2 表示 >=0.1.2 且 <0.2.0，这符合 SemVer 对不稳定版本的规定。
• Tilde (~) — ~1.2.3 等同于 >=1.2.3 且 <1.3.0。锁定次版本，仅允许补丁更新。较少使用，主要在已知次版本级别不兼容时使用。
• 精确范围 — >=1.2.0 <2.0.0 — 明确写法，提供完全控制。适用于复杂的约束，例如使用多个版本的传递依赖时。

执行 dart pub get 后，pub 会生成 pubspec.lock 文件，锁定所有已解析包（直接和传递）的精确版本。此文件应纳入版本控制系统，以确保在所有机器上可重现构建。执行 dart pub upgrade 时，lock 文件会更新到指定约束内的最新兼容版本。

dependency conflict 错误发生在两个包需要同一个依赖的不重叠范围时。pub 报告哪些包发生了冲突以及原因。解决方案：将其中一个冲突包更新到兼容版本，使用 dependency_overrides（临时措施）或用替代方案替换该包。

pub 的基本命令

所有 pub 操作都通过统一的 CLI 接口执行。在 Dart SDK 中使用 dart pub 命令，在 Flutter SDK 中使用等效的 flutter pub（额外考虑 Flutter SDK 依赖和插件）。以下是关键命令：

• dart pub get — 下载 pubspec.yaml 中指定的所有依赖，解析版本并创建/更新 pubspec.lock。在首次克隆项目或更改依赖后执行。
• dart pub upgrade — 将所有依赖更新到 pubspec.yaml 约束内的最新版本，并覆盖 pubspec.lock。可以更新单个包：dart pub upgrade http。
• dart pub add <package> — 向 pubspec.yaml 添加新的依赖并立即执行 pub get。示例：dart pub add dio 将添加 dio 包的最新版本。
• dart pub remove <package> — 从 pubspec.yaml 中删除依赖并重新启动图的解析。
• dart pub cache repair — 重新加载所有缓存的包。在本地缓存损坏或校验和错误时有用。
• dart pub deps — 以可读的文本格式显示依赖树。用于分析传递依赖和查找重复项。
• dart pub publish — 将当前包发布到 pub.dev。发布前检查 pubspec.yaml 的正确性、许可证和描述。
• dart pub outdated — 显示过时依赖列表，包含当前版本、期望版本和最新可用版本。类似于 npm outdated。

所有命令也可使用缩写形式：dart pub get 可写为 dart pub g（并非所有命令都有缩写）。在 Flutter 项目中，pub 命令前添加 flutter 前缀：flutter pub get、flutter pub add 等。Flutter 版本还额外检查插件与目标平台的兼容性。

在 pub.dev 上发布

pub.dev 是 Dart 和 Flutter 生态系统的中央包注册中心。截至 2025 年 1 月，已有超过 50,000 个包发布在此，总计下载量超过 100 亿次。每个包都有包含描述、文档、流行度评级（Popularity）、Pub Points 评分和版本的页面。

Pub Points — 自动包质量评估系统，评分范围从 0 到 130 分。考虑因素包括：许可证的存在、描述、示例、与最新稳定 Dart 版本的兼容性、无漏洞、测试覆盖率、格式化的正确性。高分能提高包在搜索中的可见度和用户信任度。

发布过程包括几个步骤：

1. 检查 pubspec.yaml：确保包含 name、description、version、license（建议指定 SPDX 标识符，例如 MIT）。
2. 运行 dart pub publish --dry-run — 模拟发布而不发送到服务器，显示将包含在包中的所有文件和可能的错误。
3. 首次发布时通过 Google 账户授权：dart pub publish 将打开浏览器进行 OAuth 认证。
4. 在终端中确认发布。成功发送后，包将在几分钟内出现在 pub.dev 上。

重要规则：只能发布具有唯一名称的包；一旦发布的版本无法删除（只能隐藏 — dart pub unpublish — 在 7 天内）；对于重大更新，应遵循语义化版本控制规则，不得在不更改主版本的情况下破坏公共 API。