“Flutter pubspec 选项”

本页主要是面向编写 Flutter 应用程序的开发者。如果你编写 package 或插件（也许你想创建一个联合插件），你应该查看 开发 package 和插件 页面。

每个 Flutter 项目都包含一个 pubspec.yaml 文件，通常被称为 pubspec。当你创建一个新的 Flutter 项目时，会生成一个基本的 pubspec。它位于项目的根目录，包含 Dart 和 Flutter 工具需要了解的项目元数据。 pubspec 是用 YAML 编写的，它具有可读性，但要注意 缩进符号（制表符和空格）很重要。

pubspec 指定了项目所需的依赖项，例如：

• 特定 package 及版本

• 字体

• 图片

• 开发者 package（如测试或模拟 package）

• 对 Flutter SDK 版本的特定限制

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

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

首次构建项目时，系统还会创建一个包含 package 特定版本的 pubspec.lock 文件。这将确保下次构建项目时获得相同的版本。

以下是 Flutter 项目 pubspec 文件的示例。仅 Flutter 字段和 package 突出显示。

name: <project name>
description: A new Flutter project.
​
publish_to: none
version: 1.0.0+1
​
environment:
  sdk: ^3.12.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
​
  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.png
    - images/a_dot_ham.png
​
  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 特定字段和 Dart 特定字段可以添加到 Flutter pubspec 中。要了解相关 Flutter 特定字段的更多信息，请参阅下面的章节。要了解相关 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 ]
    [...]

# 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

assets 的子字段：

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

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

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

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

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

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

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

你可以传入文件路径：

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

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

NOTE: This feature is only available as of #167953 on the main channel.

NOTE: 此特性仅在 main channel 上的 #167953 之后可用。

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

flutter:
  config:
    cli-animations: false
    enable-swift-package-manager: true

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

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

为应用程序指定默认的 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 的延迟加载组件。

禁用 Swift Package Manager (SPM)，使其不再管理你的 iOS 和 macOS Flutter 项目中的依赖项。

flutter:
  disable-swift-package-manager: true

NOTE: As of #168433 on the main channel, this property has moved to the config section:

pubspec.yaml

yaml

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

content_copy

NOTE: 从 main channel 上的 #168433 起，此属性已移至 config 部分：

pubspec.yaml

yaml

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

content_copy

包含应用 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

处理本地化任务。该字段可以作为 flutter 和 material 的子字段出现。

启用通用本地化：

flutter:
  generate: true

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

licenses 字段具有以下结构：

flutter:
  licenses:
    - [path_to_file]

专门为 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

在 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 测试或集成测试，请使用它。

dependencies:
  flutter_test:
    sdk: flutter

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

dev_dependencies:
  flutter_lints: ^6.0.0

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

dependencies:
  cupertino_icons: ^1.0.0

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

• dart.dev 上介绍的 创建 package

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

• dart.dev 上介绍的 package 的依赖

• dart.dev 上介绍的 使用 package

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