“Flutter pubspec 选项”

每个用 Dart 编写的项目以及所有 Flutter 应用和库，都包含一个 pubspec.yaml 文件，通常被称为 pubspec。当你创建一个新项目时，会生成一个基本的 pubspec 文件，它位于项目的根目录，包含项目元数据并列出了项目的依赖项。

Dart 和 Flutter 项目共有的字段在 dart.dev 的 pubspec 文件 中进行说明。 本页只列出了对 Flutter 项目适用的字段。

当你用 flutter create 命令创建一个新项目时（或通过使用你的 IDE 中的相应按钮），它会为每一个 Flutter 应用程序创建 pubspec。

首次构建项目时，系统还会创建一个包含 package 特定版本的 pubspec.lock 文件。这将确保下次构建项目时获得相同的版本。如果需要进一步了解 Flutter 和 Dart 的 package 依赖项， Package 依赖管理。

以下 pubspec 文件示例突出了仅在 Flutter 应用中使用的字段，关于未突出显示的字段信息，请查阅 dart.dev。

name: <project name>
description: A new Flutter project.
​
publish_to: 'none'  # Remove this line if you wish to publish to pub.dev
version: 1.0.0+1
​
environment:
  sdk: ^3.13.0
​
dependencies:
  flutter:       # Required for every Flutter project
    sdk: flutter # Required for every Flutter project
  flutter_localizations: # Required to enable localization
    sdk: flutter         # Required to enable localization
​
  cupertino_icons: ^1.0.8 # Only required if you use Cupertino (iOS style) icons
​
dev_dependencies:
  flutter_test:
    sdk: flutter # Required for a Flutter project that includes tests
  integration_test:
    sdk: flutter # Required for integration tests
​
  flutter_lints: ^6.0.0 # Contains a set of recommended lints for Flutter code
​
flutter:
​
  uses-material-design: true # Required if you use the Material icon font
​
  generate: true # Enables generation of localized strings from arb files
​
  config: # App-specific configuration flags that mirror `flutter config`
    enable-swift-package-manager: true
​
  assets:  # Lists assets, such as image files
    - images/a_dot_burr.jpeg
    - images/a_dot_ham.jpeg
​
  licenses: # Lists additional license files to be bundled with the app
    - assets/my_license.txt
​
  fonts:              # Required if your app uses custom fonts
    - family: Schyler
      fonts:
        - asset: fonts/Schyler-Regular.ttf
        - asset: fonts/Schyler-Italic.ttf
          style: italic
    - family: Trajan Pro
      fonts:
        - asset: fonts/TrajanPro.ttf
        - asset: fonts/TrajanPro_Bold.ttf
          weight: 700

本页仅适用于 Flutter 的 pubspec 字段。更多通用的 Dart 字段，请参阅 Dart pubspec 支持的字段。

应用使用的静态资源路径列表。这些静态资源与应用程序捆绑在一起。常见的静态资源类型包括静态数据（例如JSON）、配置文件、图标和图像（JPEG、WebP、GIF、动画 WebP/GIF、PNG、BMP 和 WBMP）。

除了列出应用 package 中包含的图片，一个图片资源还可以引用一个或多个特定分辨率的「变体」。想要了解更多信息，请参阅 资源和图像 页面的 分辨率相关 部分。关于从 package 的依赖关系中添加资源的信息，见同一页的 package 依赖关系中的图片资源 部分。

asset 字段具有以下结构：

flutter:
  assets:
    - [ path_to_file | path_to_directory ]
      [ flavor_path_field | platform_path_field | transformer_path_field ]
    [...]

# path_to_file structure
- path/to/directory/file

# path_to_directory structure
- path/to/directory/

# flavor_path_field structure
- path: path/to/directory
  flavors:
    - flavor_name

# platform_path_field structure
- path: path/to/file
  platforms:
    - platform_name

# transformer_path_field structure
- path: path/to/file
  transformers:
    - package: transformer_package_name
      args: ['arg1', 'arg2'] # Optional

assets 的子字段：

• path_to_file：表示文件路径的字符串。

• path_to_directory：表示目录路径的字符串。

• flavor_path_field：路径字段和 flavor 的子字段。

• platform_path_field：路径字段及其平台子字段。

• transformer_path_field: A path field and its transformer subfields.

• path：资产文件和目录路径。

• flavors：用于特定路径资源的 Flutter flavor 列表。要了解相关 flavor 的更多信息，请参阅 为 iOS 和 macOS 设置 flavor 和 为 Android 设置 flavor。

• platforms：在特定路径下使用资源的平台列表。有效值为 android、ios、web、linux、macos 和 windows。

• transformers：在构建时对资源运行的转换器 package 的列表。更多信息，请参考 构建时转换资源。

你可以传入文件路径：

flutter:
  assets:
    - assets/images/my_image_a.png
    - assets/images/my_image_b.png

你可以传入目录路径：

flutter:
  assets:
    - assets/images/
    - assets/icons/

你可以为特定 flavor 传入目录路径：

flutter:
  assets:
    - path: assets/flavor_a_and_b/images
      flavors:
        - flavor_a
        - flavor_b
    - path: assets/flavor_c/images
      flavors:
        - flavor_c

你可以为特定平台传入文件路径：

flutter:
  assets:
    - path: assets/web_worker.js
      platforms:
        - web
    - path: assets/desktop_icon.png
      platforms:
        - windows
        - linux
        - macos

You can configure build-time asset transformers:

flutter:
  assets:
    - path: assets/logo.svg
      transformers:
        - package: vector_graphics_compiler
          args: ['--tessellate']

一个由键映射到标记（true 或 false）的字典，它会影响 flutter CLI 的执行方式。

可用的键与 flutter config --list 中可用的键相对应。

flutter:
  config:
    cli-animations: false

使用 flutter config --help 查看每个标记的说明。

标记仅从当前的 应用程序 package 中读取，在 package 或依赖项的上下文中不起作用。

控制 Flutter 是否使用 Swift Package Manager 来管理该项目的原生 iOS 和 macOS 依赖项。若要为该项目禁用此功能，请将该字段设置为 false。

flutter:
  config:
    enable-swift-package-manager: false

为应用程序指定默认的 Flutter flavor。使用时，你无需在 Flutter 启动命令中包含此 flavor 的名称。

flutter:
  default-flavor: flavor_name

在下面的示例中， Android Flutter 应用程序有名为 staging 和 production 的 flavor。 production flavor 是默认 flavor。运行该 flavor 时，无需在启动命令中包含它。

flutter:
  default-flavor: production

# Use this command to run the default flavor (production).
$ flutter run

# Use this command to run non-default flavors (staging).
$ flutter run --flavor staging

要了解如何创建 Flutter flavor，请参阅 为 Android 设置 Flutter flavor 和 为 iOS 和 macOS 设置 Flutter flavor。

延迟下载组件来减少 Android 应用初始的下载体积。常用于大型应用、模块化应用，以及具有按需特性的应用。

deferred-components 字段具有以下结构：

flutter:
  deferred-components:
    - name: component_name
      libraries:
        - string_expression
        [...]
      assets:
        - string_expression
        [...]
    [...]

延迟组件的子字段：

• name：特定延迟组件的唯一标识符。

• libraries：作为延迟组件一部分的 Dart 库列表。

• assets：与延迟组件相关联的静态资源路径列表。

示例：

flutter:
  deferred-components:
    - name: box_component
      libraries:
        - package:testdeferredcomponents/box.dart
    - name: gallery_feature
      libraries:
        - package:testdeferredcomponents/gallery_feature.dart
      assets:
        - assets/gallery_images/gallery_feature.png

要了解关于如何在 Flutter Android 应用中使用延迟组件的更多信息，请参阅 Android 的延迟加载组件。

包含应用 Flutter 特定设置的字段。

flutter:
  [flutter_field]
  [...]

在 Flutter 应用程序中配置并包含自定义字体。

关于使用字体的例子，请参见 Flutter 实用教程中的 使用自定义字体 和 从 package 中导出字体 教程。

fonts 字段具有以下结构：

flutter:
  fonts:
    -  { font_family_field | font_asset_field }
    [...]

# font_family_field structure
- family: font_name
  fonts:
    - font_asset_field
    [...]

# font_asset_field structure
- asset: path/to/directory/font_name
  weight: int_expression # Optional
  style: string_expression # Optional

fonts 的子字段：

• family：可选项。字体 family 名称。可以有多个字体静态资源。

• asset：使用的字体。

• weight：可选项。字体的字重。可以是 100、200、300、400、500、600、700、800 或者 900。

• style：可选项，字体的样式。可以是 italic。

使用不属于字体 family 的字体：

flutter:
  fonts:
    - asset: fonts/Roboto-Regular.ttf
      weight: 900 # Optional
      style: italic # Optional

使用字体 family：

flutter:
  fonts:
    - family: Roboto # Optional
      fonts:
        - asset: fonts/Roboto-Regular.ttf
        - asset: fonts/Roboto-Bold.ttf
          weight: 700 # Optional
          style: italic # Optional

另外，如果你有一种不需要 family、字重或样式要求的字体，你可以将其声明为简单的静态资源：

flutter:
  assets:
    - fonts/Roboto-Regular.ttf

支持从 .arb 文件生成包含本地化字符串的 Dart 文件。

启用通用本地化：

flutter:
  generate: true

更多信息，参考 Flutter 的国际化。

应与应用程序捆绑在一起的额外许可证文件路径列表。这些文件通常位于项目的 assets 目录中。

licenses 字段具有以下结构：

flutter:
  licenses:
    - [path_to_file]

Configure settings for a Flutter module project when adding Flutter to an existing host Android or iOS application (Add-to-App).

The module field has the following structure:

flutter:
  module:
    androidPackage: com.example.my_module # Optional
    iosBundleIdentifier: com.example.myModule # Optional

Subfields of module:

• androidX: Optional. Specifies whether the module uses AndroidX.
• androidPackage: Optional. The package name used for generated Android code.
• iosBundleIdentifier: Optional. The bundle identifier used for generated iOS code.

To learn more, visit Add Flutter to existing apps.

专门为 Flutter 插件配置设置。

plugin 字段具有以下结构：

flutter:
  plugin:
    platforms:
      android: # Optional
        package: com.example.my_plugin
        pluginClass: MyPlugin
        dartPluginClass: MyPluginClassName
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
      ios: # Optional
        pluginClass: MyPlugin
        dartPluginClass: MyPluginClassName
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
        sharedDarwinSource: true
      macos: # Optional
        pluginClass: MyPlugin
        dartPluginClass: MyPluginClassName
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
        sharedDarwinSource: true
      windows: # Optional
        pluginClass: MyPlugin
        dartPluginClass: MyPluginClassName
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
      linux: # Optional
        pluginClass: MyPlugin
        dartPluginClass: MyPluginClassName
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
      web: # Optional
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
    implements: # Optional
      - example_platform_interface

plugin 的子字段：

• platforms：将拥有配置设置的平台列表。

• package：插件的 Android package 名称。可用于 Android 平台，且是必需的。

• pluginClass：插件类的名称。如果同一平台使用了 dartPluginClass，则为可选项。可用于 Android、iOS、Linux、macOS 和 Windows 平台。

• default_package：可选项。应被用作平台接口默认实现的 package。仅适用于联合插件，即插件的实现被拆分为多个特定平台的 package。

• dartPluginClass：可选项。作为 Flutter 插件入口点的 Dart 类。可用于 Android、iOS、Linux、macOS 和 Windows 平台。

• sharedDarwinSource：可选项。表示插件在 iOS 和 macOS 之间共享原生代码。可用于 iOS 和 macOS 平台。

• fileName：可选项。包含插件类的文件。

• ffiPlugin：可选项。如果插件使用了外部函数接口 (FFI)，则为 True。

• implements：可选项。Flutter 插件实现的平台接口。

要了解关于插件的更多信息，请参阅 开发 package 和插件。

带有 .frag 扩展名的 GLSL 着色器，必须在项目 pubspec.yaml 文件的 shaders 部分声明。 Flutter 命令行工具会将着色器编译为相应的后端格式，并生成其所需的运行时元数据。编译后的着色器随后会像静态资源一样被包含在应用程序中。

shaders 字段具有以下结构：

flutter:
  shaders:
    -  { path_to_file | path_to_directory }
    [...]

# path_to_file structure
- assets/shaders/file

# path_to_directory structure
- assets/shaders/

添加特定的着色器：

flutter:
  shaders:
    - assets/shaders/shader_a.frag
    - assets/shaders/shader_b.frag

添加一个着色器目录：

flutter:
  shaders:
    - assets/shaders/

或者，你可以将着色器目录添加到 assets 字段：

flutter:
  assets:
    - assets/shaders/my_shader.frag

Like other assets, shaders also support flavors and transformers.

在 Flutter 应用中使用 Material Design 组件和图标字体。

flutter:
  uses-material-design: true

以下 Flutter 特定的 package 可以添加到 pubspec 中。如果你添加了一个 package，请在终端中运行 flutter pub get 来安装该 package。

代表 Flutter SDK 自身的 package，可以添加到 dependencies 字段。如果你的项目依赖于 Flutter SDK，而非来自 pub.dev 的常规 package，请使用它。

dependencies:
  flutter:
    sdk: flutter

代表 Flutter SDK 自身的 package，可以添加到 dependencies 字段。使用它来启用 ARB 文件的本地化。通常与 intl package 一起使用。

dependencies:
  flutter_localizations:
    sdk: flutter
  intl: any

代表 Flutter SDK 自身的 package，可以添加到 dependencies 字段。如果你的 Flutter 应用有单元测试、widget 测试或集成测试，请使用它。

dev_dependencies:
  flutter_test:
    sdk: flutter

A package provided by the Flutter SDK for running integration tests on target devices or emulators.

dev_dependencies:
  integration_test:
    sdk: flutter

更多信息，参考 集成测试。

为 Flutter 项目提供一组推荐 lint 规则的 package。该 package 可以添加到 pubspec 的 dev_dependencies 字段。

dev_dependencies:
  flutter_lints: ^6.0.0

提供一组 Apple Cupertino 图标供 Flutter 应用使用的 package。该 package 可以添加到 pubspec 的 dependencies 字段。

dependencies:
  cupertino_icons: ^1.0.8

要查看更多有关 package、插件和 pubspec 的信息，请参考下面文档：

• 将 Flutter 添加到现有应用

• dart.dev 上介绍的 创建 package

• dart.dev 上介绍的 package 的术语表

• 集成测试

• Package 依赖管理

• dart.dev 上介绍的 Package 依赖项

• 为 Android 配置 Flutter flavors

• 为 iOS 和 macOS 配置 Flutter flavors

• 在构建时转换资源

• 使用 package

• dart.dev 上介绍的 避免提交的内容