Flutter pubspec 配置选项

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

每个 Flutter 项目都包含一个 pubspec.yaml 文件，通常被称为 pubspec。当你创建一个新的 Flutter 项目时，会生成一个基本的 pubspec 文件。它位于项目树的顶部，包含 Dart 和 Flutter 工具需要了解的项目元数据。pubspec 使用 YAML 编写，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.8.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

  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）。

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

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

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

注意：此功能仅在 main 渠道上的 #167953 版本中可用。

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

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

标志仅从当前应用包中读取，对包或依赖项无效。

为应用分配一个默认的 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 包管理器 (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

配置 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：可选。如果插件使用外部函数接口 (FFI)，则为 true。
implements：可选。Flutter 插件实现的平台接口。

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

具有 FRAG 扩展名的 GLSL 着色器必须在项目的 pubspec.yaml 文件的着色器部分中声明。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 文件的更多信息，请参阅以下内容：

创建包（在 dart.dev 上）
包术语表（在 dart.dev 上）
包依赖项（在 dart.dev 上）
使用包
不应提交的内容（在 dart.dev 上）

此页面内容有帮助吗？

感谢你的反馈！

提供详情

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

提供详情

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

Flutter pubspec 配置选项

概述

示例

字段

assets 字段

config 字段

default-flavor 字段

deferred-components 字段

disable-swift-package-manager 字段

flutter 字段

fonts 字段

generate 字段

plugin 字段

shaders 字段

uses-material-design 字段

包

flutter 包

flutter_localizations 包

flutter_test 包

flutter_lints 包

cupertino_icons

更多信息