“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.7.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: ^5.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

  assets:  # Lists assets, such as image files
    - images/a_dot_burr.png
    - images/a_dot_ham.png

  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 ]
    [...]

# path_to_file structure
- path/to/directory/file

# path_to_directory structure
- path/to/directory/

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

assets 的子字段：

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

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

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

• path：目录的路径。

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

你可以传入文件路径：

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 flavor。使用时，你无需在 Flutter 启动命令中包含此 flavor 的名称。

flutter:
  default-flavor: flavor_name # Android-only field

在下面的示例中， 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。

Defer initial the download size of an Android app. Most often used with large applications, modularized applications, and applications with on-demand features.

The deferred-components field has this structure:

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

Deferred component subfields:

• name: The unique identifier for a specific deferred component.
• libraries: A list of Dart libraries that are part of the deferred component.
• assets: A list of asset paths that are associated with the deferred component.

Example:

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

To learn more about how you can use deferred components with a Flutter Android app, see Deferred components for Android.

Disable the use of the Swift Package Manager (SPM) so that it no longer manages dependencies in your iOS and macOS Flutter projects.

flutter:
  disable-swift-package-manager: true

A field that contains Flutter-specific settings for your app.

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

Configure settings specifically for Flutter plugins.

The plugin field has this structure:

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

Subfields of plugin:

• platforms: A list of platforms that will have configuration settings.
• package: The Android package name of the plugin. This can be used with the Android platform and is required.
• pluginClass: The name of the plugin class. Optional if dartPluginClass is used for the same platform. This can be used with the Android, iOS, Linux macOS, and Windows platforms.
• default_package: Optional. The package that should be used as the default implementation of a platform interface. Only applicable to federated plugins, where the plugin's implementation is split into multiple platform-specific packages.
• dartPluginClass: Optional. The Dart class that serves as the entry point for a Flutter plugin. This can be used with the Android, iOS, Linux macOS, and Windows platforms.
• sharedDarwinSource: Optional. Indicates that the plugin shares native code between iOS and macOS. This can be used with the iOS and macOS platforms.
• fileName: Optional. The file that contains the plugin class.
• ffiPlugin: Optional. True if the plugin uses a Foreign Function Interface (FFI).
• implements: Optional. The platform interfaces that a Flutter plugin implements.

To learn more about plugins, see Developing packages & plugins.

GLSL Shaders with the FRAG extension, must be declared in the shaders section of your project's pubspec.yaml file. The Flutter command-line tool compiles the shader to its appropriate backend format, and generates its necessary runtime metadata. The compiled shader is then included in the application just like an asset.

The shaders field has this structure:

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

# path_to_file structure
- assets/shaders/file

# path_to_directory structure
- assets/shaders/

Add specific shaders:

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

Add a directory of shaders:

flutter:
  shaders:
    - assets/shaders/

Alternatively, you can add your shader directory to the assets field:

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

Use Material Design components in your Flutter app.

flutter:
  uses-material-design: true

The following Flutter-specific packages can be added to the pubspec. If you add a package, run flutter pub get in your terminal to install the package.

A package that represents the Flutter SDK itself and can be added to the dependencies field. Use this if your project relies on the Flutter SDK, not a regular package from pub.dev.

dependencies:
  flutter:
    sdk: flutter

A package that represents the Flutter SDK itself and can be added to the dependencies field. Use this to enable the localization of ARB files. Often used with the intl package.

dependencies:
  flutter_localizations:
    sdk: flutter
  intl: ^0.18.0

A package that represents the Flutter SDK itself and can be added to the dependencies field. Use this if you have unit, widget, or integration tests for your Flutter app.

dependencies:
  flutter_test:
    sdk: flutter

A package that that provides a set of recommended lints for Flutter projects. This package can be added to the dev_dependency field in the pubspec.

dev_dependencies:
  flutter_lints: ^2.0.0

A package that provides a set of Apple's Cupertino icons for use in Flutter applications. This package can be added to the dependency field in the pubspec.

dependencies:
  cupertino_icons: ^1.0.0

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

• dart.dev 上介绍的 创建 package

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

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

• dart.dev 上介绍的 使用 package

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