Flutter pubspec 选项

此页面主要面向 Flutter 应用开发者。如果您开发的是包或插件（可能您想创建联合插件），您应该查阅开发包和插件页面。

每个 Flutter 项目都包含一个 pubspec.yaml 文件，通常称为 pubspec。当您创建新 Flutter 项目时，会生成一个基本的 pubspec 文件。它位于项目树的顶部，包含 Dart 和 Flutter 工具所需了解的项目元数据。pubspec 使用 YAML 格式编写，该格式人类可读，但请注意空格（制表符与空格）很重要。

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

特定的包及其版本
字体
图片
开发者包（例如测试或模拟包）
对 Flutter SDK 版本的特定约束

Dart 和 Flutter 项目共有的字段在 dart.dev 上的 pubspec 文件中有描述。此页面列出了仅适用于 Flutter 项目的 Flutter 特定字段和包。

当您使用 flutter create 命令（或使用 IDE 中的相应按钮）创建新项目时，它会为基本的 Flutter 应用创建一个 pubspec 文件。

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

以下是 Flutter 项目 pubspec 文件的示例。Flutter 特有字段和包已突出显示。

pubspec.yaml
yamlname: <project name>
description: A new Flutter project.

publish_to: none
version: 1.0.0+1

environment:
  sdk: ^3.9.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）。

除了列出包含在应用包中的图像外，图像资源还可以指向一个或多个分辨率特定的“变体”。有关更多信息，请参阅 Assets and images 页面的分辨率感知部分。有关从包依赖项添加资源的信息，请参阅同一页面中的包依赖项中的图像资源部分。

asset 字段具有此结构

pubspec.yaml
yamlflutter:
  assets:
    - [ path_to_file | path_to_directory ]
      [ flavor_path_field ]
    [...]

yaml# path_to_file structure
- path/to/directory/file

yaml# path_to_directory structure
- path/to/directory/

yaml# 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。

您可以提供文件路径

pubspec.yaml
yamlflutter:
  assets:
    - assets/images/my_image_a.png
    - assets/images/my_image_b.png

您可以提供目录路径

pubspec.yaml
yamlflutter:
  assets:
    - assets/images/
    - assets/icons/

您可以为特定 flavor 提供目录路径

pubspec.yaml
yamlflutter:
  assets:
    - path: assets/flavor_a_and_b/images
      flavors:
      - flavor_a
      - flavor_b
    - path: assets/flavor_c/images
      flavors:
      - flavor_c

用于影响 flutter CLI 执行方式的键到标志（true 或 false）的映射。

注意：此功能仅在 main 分支的 #167953 中可用。

可用键镜像 flutter config --list 中可用的键。

pubspec.yaml
yamlflutter:
  config:
    cli-animations: false
    enable-swift-package-manager: true

使用 flutter config --help 获取每个标志的说明。

标志仅从当前应用程序包读取，在包或依赖项的上下文中无效。

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

pubspec.yaml
yamlflutter:
  default-flavor: flavor_name

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

pubspec.yaml
yamlflutter:
  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 字段具有此结构

pubspec.yaml
yamlflutter:
  deferred-components:
    name: component_name
      libraries:
        - string_expression
        [...]
      assets:
        - string_expression
        [...]
    [...]

延迟组件子字段

name：特定延迟组件的唯一标识符。
libraries：属于延迟组件的 Dart 库列表。
assets：与延迟组件关联的资源路径列表。

示例

pubspec.yaml
yamlflutter:
  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 项目中的依赖项。

pubspec.yaml
yamlflutter:
  disable-swift-package-manager: true

注意：从 main 分支的 #168433 开始，此属性已移至 config 部分。
pubspec.yaml
yaml
flutter:
  config:
    enable-swift-package-manager: false

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

pubspec.yaml
yamlflutter:
  [flutter_field]
  [...]

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

有关使用字体的示例，请参阅 Flutter 食谱中的使用自定义字体和从包导出字体。

fonts 字段具有此结构

pubspec.yaml
yamlflutter:
  fonts:
    -  { font_family_field | font_asset_field }
    [...]

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

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

fonts 的子字段

family：可选。字体系列名称。可以包含多个字体资源。
asset：要使用的字体。
weight：可选。字体的粗细。可以是 100、200、300、400、500、600、700、800 或 900。
style：可选。字体的样式。可以是 italic。

使用不属于字体系列的字体

pubspec.yaml
yamlflutter:
  fonts:
    - asset: fonts/Roboto-Regular.ttf
      weight: 900 # Optional
      style: italic # Optional

使用字体系列

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

或者，如果您有一个不需要系列、粗细或样式要求的字体，您可以将其声明为简单资源

pubspec.yaml
yamlflutter:
  assets:
    - fonts/Roboto-Regular.ttf

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

启用通用本地化

pubspec.yaml
yamlflutter:
  generate: true

要添加到应用程序的附加许可证文件路径列表。这些文件通常位于项目目录的 assets 中。

licenses 字段具有此结构

pubspec.yaml
yamlflutter:
  licenses:
    - [path_to_file]

专门为 Flutter 插件配置设置。

plugin 字段具有此结构

pubspec.yaml
yamlflutter:
  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 包名称。可与 Android 平台一起使用，并且是必需的。
pluginClass：插件类的名称。如果为同一平台使用了 dartPluginClass，则此项是可选的。可与 Android、iOS、Linux、macOS 和 Windows 平台一起使用。
default_package：可选。将用作平台接口默认实现的包。仅适用于联合插件，其中插件实现被拆分为多个特定于平台的包。
dartPluginClass：可选。作为 Flutter 插件入口点的 Dart 类。可与 Android、iOS、Linux、macOS 和 Windows 平台一起使用。
sharedDarwinSource：可选。指示插件在 iOS 和 macOS 之间共享原生代码。可与 iOS 和 macOS 平台一起使用。
fileName：可选。包含插件类的文件。
ffiPlugin：可选。如果插件使用 Foreign Function Interface (FFI)，则为 true。
implements：可选。Flutter 插件实现的平台接口。

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

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

shaders 字段具有此结构

pubspec.yaml
yamlflutter:
  shaders:
    -  { path_to_file | path_to_directory }
    [...]

yaml# path_to_file structure
- assets/shaders/file

yaml# path_to_directory structure
- assets/shaders/

添加特定着色器

pubspec.yaml
yamlflutter:
  shaders:
    - assets/shaders/shader_a.frag
    - assets/shaders/shader_b.frag

添加着色器目录

pubspec.yaml
yamlflutter:
  shaders:
    - assets/shaders/

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

pubspec.yaml
yamlflutter:
  assets:
    - assets/shaders/my_shader.frag

在您的 Flutter 应用中使用 Material Design 组件。

pubspec.yaml
yamlflutter:
  uses-material-design: true

可以将以下 Flutter 特有包添加到 pubspec 中。如果添加了包，请在终端中运行 flutter pub get 来安装该包。

代表 Flutter SDK 本身的包，可添加到 dependencies 字段。如果您的项目依赖于 Flutter SDK，而不是 pub.dev 上的常规包，请使用此项。

pubspec.yaml
yamldependencies:
  flutter:
    sdk: flutter

代表 Flutter SDK 本身的包，可添加到 dependencies 字段。使用此项可启用 ARB 文件的本地化。通常与 intl 包一起使用。

pubspec.yaml
yamldependencies:
  flutter_localizations:
    sdk: flutter
  intl: any

代表 Flutter SDK 本身的包，可添加到 dependencies 字段。如果您的 Flutter 应用有单元、widget 或集成测试，请使用此项。

pubspec.yaml
yamldependencies:
  flutter_test:
    sdk: flutter

提供一组推荐的 Flutter 项目 lint 的包。此包可以添加到 pubspec 的 dev_dependency 字段中。

pubspec.yaml
yamldev_dependencies:
  flutter_lints: ^6.0.0

提供一套 Apple 的 Cupertino 图标供 Flutter 应用程序使用的包。此包可以添加到 pubspec 的 dependency 字段中。

pubspec.yaml
yamldependencies:
  cupertino_icons: ^1.0.0

有关包、插件和 pubspec 文件的更多信息，请参阅以下内容：

此页面内容有帮助吗？

感谢你的反馈！

提供详情

感谢你的反馈！请告诉我们如何改进。

提供详情

除非另有说明，本网站上的文档反映了 Flutter 的最新稳定版本。页面最后更新于 2025-09-02。查看源代码或报告问题。

概述

示例

字段

assets 字段

config 字段

default-flavor 字段

deferred-components 字段

disable-swift-package-manager 字段

flutter 字段

fonts 字段

generate 字段

licenses 字段

plugin 字段

shaders 字段

uses-material-design 字段

包

flutter 包

flutter_localizations 包

flutter_test 包

flutter_lints 包

cupertino_icons

更多信息