pubspec.yaml — 是什么、结构以及 Flutter 中的依赖配置

什么是 pubspec.yaml

pubspec.yaml — 是一个 YAML 格式的清单文件，pub 包管理器使用它来管理 Dart 和 Flutter 项目。它位于项目的根目录，每次执行 flutter pub get 命令时都会被处理。与其他平台配置分布在多个文件中不同，Flutter 使用一个集中式清单来满足所有需求。

该文件包含元数据：项目名称、描述、版本、作者。这些数据在向 pub.dev 发布包以及为 App Store 和 Google Play 构建应用程序时使用。description 字段会显示在包的搜索结果中，因此它应该包含信息量，并包含其他开发人员可以找到该库的关键词。

没有正确的 pubspec.yaml，Flutter 项目就无法构建。语法错误或不正确的缩进会立即导致编译失败，并显示 Error on line X 消息。YAML 对空格敏感：多一个空格会改变数据结构，制表符会导致语法错误。因此，在手动编辑 pubspec.yaml 时，使用支持 YAML 语法高亮的编辑器非常重要，例如带有官方 Flutter 扩展的 VS Code。

pubspec.yaml 的主要部分

pubspec.yaml 由必填和可选部分组成。每个部分负责项目配置的特定方面。部分的顺序并不重要，但根据社区惯例，遵循一定的层次结构：元数据、环境、依赖项、资源、平台。

name 和 description

name 字段设置包的唯一标识符，采用 snake_case 格式，仅由小写拉丁字母、数字和下划线组成。description 字段 — 项目的简短描述，最多 180 个字符，是向 pub.dev 发布所必需的。描述应说明包的用途，不要重复名称，并包含用于存储库搜索优化的关键词。

name: my_flutter_app
description: 使用 Flutter 的任务管理应用
publish_to: 'none'

version 和 environment

version 字段使用语义化版本管理 major.minor.patch，加号后带有可选的构建编号（1.0.0+1）。environment 部分设置 Dart 和 Flutter SDK 的最低和最高版本以确保兼容性。如果新版本的 SDK 包含与项目代码不兼容的严重更改，编译将停止并显示清晰的错误消息。

version: 1.0.0+1
environment:
  sdk: '>=3.2.0 <4.0.0'
  flutter: '>=3.16.0'

dependencies 和 dev_dependencies

dependencies 部分列出应用程序运行时所需的包。dev_dependencies 部分包含用于测试、代码生成和开发的包 — 它们不会包含在发布版本中。依赖项的划分对性能至关重要：dependencies 中的每个包都会增加最终 APK 或 IPA 的大小，并且由于初始化额外的库而增加应用程序的启动时间。

dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.0
  provider: ^6.1.0
  shared_preferences: ^2.2.0
  cached_network_image: ^3.3.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  mockito: ^5.4.0
  build_runner: ^2.4.0

配置 assets 和字体

flutter 部分包含用于配置资源、字体和平台参数的子部分。资源通过 paths 数组连接，指定具体文件或整个目录。所有路径都是相对于项目根目录指定的，而不是相对于 pubspec.yaml。这是一个重要的细节，经常导致 Flutter 初学者感到困惑。

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    - assets/icons/
    - assets/config.json
    - assets/data/translations/
  fonts:
    - family: RobotoMono
      fonts:
        - asset: fonts/RobotoMono-Regular.ttf
        - asset: fonts/RobotoMono-Bold.ttf
          weight: 700
        - asset: fonts/RobotoMono-Italic.ttf
          style: italic

通过 pubspec.yaml 连接 assets 使文件在运行时可以通过 AssetBundle 访问。这适用于图像、JSON、文本文件和任何其他资源。Flutter 自动支持不同的屏幕分辨率：如果您放置 images/2x/ 和 images/3x/，Flutter 将根据设备的 device pixel ratio 选择图像的适当版本。为此，只需在 assets 中指定 images/ 根文件夹即可。

自定义字体通过 fonts 部分添加，指定 family 和字体列表。更改 pubspec.yaml 后，需要执行 flutter pub get 以应用设置。字体既可以在 MaterialApp 主题中全局使用，也可以在特定 widget 中局部使用。对于每种字体，可以指定 weight（100-900）和 style（normal, italic），这使 Flutter 能够在代码中使用 FontWeight 和 FontStyle 时正确选择字体文件。

管理依赖项和版本

pub 支持多种指定依赖项来源的方式：pub.dev、Git 存储库、本地路径和私有存储库。来源的选择取决于开发阶段：稳定版本使用 pub.dev，分支和自定义修改使用 Git，并行开发的库使用本地路径。

^version 运算符表示兼容版本：^1.2.0 允许 >=1.2.0 且 <2.0.0 的版本。这类似于 CocoaPods 中的 ~> 运算符和 npm 中的 Caret 运算符。pub 通过 SAT 求解算法自动解决依赖地狱问题，该算法找到满足所有约束的版本组合。如果不存在这样的组合，pub 会显示详细消息，指出冲突的包。

pubspec.lock 文件固定了依赖项的确切版本。对于应用程序，它应保存在版本控制系统中，以确保团队所有机器上的可重现构建。对于库，pubspec.lock 不包含在存储库中，因为库的用户应该能够将其与不同版本的依赖项一起使用。flutter pub upgrade 命令根据 pubspec.yaml 的约束更新所有依赖项，flutter pub outdated 显示哪些包可以更新。

配置构建和发布

要在 pub.dev 上发布应用程序，需要在 publish_to 部分指定设置。值 'none' 禁止意外发布包，这对于内部或非公开项目很重要。如果 publish_to 不存在，pub 会尝试将包发布到默认的 pub.dev，这可能导致意外的代码泄漏。

flutter 部分包含平台参数：generate 用于自动生成平台文件，deferred-components 用于模块化加载功能。参数 generate: true 使 Flutter 在通过 flutter create --platforms 添加新平台时自动创建和更新平台项目（iOS、Android、Web）。没有此参数，平台文件夹的结构可能与 pubspec.yaml 失去同步。

flutter:
  generate: true
  deferred-components:
    - name: photoEditor
      libraries:
        - package:photo_editor/library.dart

platforms 部分设置包的目标平台。对于应用程序，在通过 flutter create 添加对特定平台的支持时会自动确定。可以通过编辑 pubspec.yaml 手动添加和删除平台。Deferred Components 允许按需加载应用程序的部分，从而减小安装大小 — 这对于游戏和包含大量不常使用内容的应用程序尤其重要。

发布包时，pub 会检查 pubspec.yaml 的所有字段是否符合存储库的要求。缺少必填字段 name、version 和 description 会导致发布被拒绝。此外，还会检查许可证的有效性、README.md 和 CHANGELOG.md 的存在。代码分析器（dart analyze）存在错误的包也无法通过验证。成功发布后，包会在几分钟内在 pub.dev 上可用。

dependency_overrides 部分允许强制指定包的版本，忽略来自传递依赖项的限制。这是一个强大但危险的机制：如果使用不当，可能导致库不兼容。只能临时使用 dependency_overrides 来解决冲突或测试新版本。修复主要依赖项后，应删除 override，以免长期破坏项目的依赖关系图。

pubspec.yaml 中的 executables 部分允许指定在激活包时 pub 安装到 PATH 的可执行脚本。这对于用 Dart 编写的 CLI 工具非常有用，例如 build_runner 或 dart_code_metrics。dart pub global activate 命令全局安装包，使 executables 中指定的脚本可以从终端使用。对于应用程序，通常不使用 executables，因为入口点是通过 lib/main.dart 中的 main 确定的。