Flutter pubspec 选项

描述 pubspec 文件中的 Flutter 专用字段。

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

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

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

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

Dart 和 Flutter 项目通用的字段在 pubspec 文件（位于 dart.dev 上）中描述。此页面列出了Flutter 专用字段和仅对 Flutter 项目有效的包。

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

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

以下是一个 Flutter 项目 pubspec 文件的示例。Flutter 专用字段和包已突出显示。

pubspec.yaml

yaml

name: <project name>
description: A new Flutter project.

publish_to: none
version: 1.0.0+1

environment:
  sdk: ^3.10.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 pubspec 添加 Flutter 专用字段和 Dart 专用字段。要了解有关 Flutter 专用字段的更多信息，请参阅以下部分。要了解有关 Dart 专用字段的更多信息，请参阅 Dart 的 pubspec 支持的字段。

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

除了列出包含在应用程序包中的图像之外，图像资产还可以引用一个或多个特定分辨率的“变体”。有关更多信息，请参阅分辨率感知部分，以及资产和图像页面。有关如何添加来自包依赖项的资产，请参阅同一页面的包依赖项中的资产图像部分。

asset 字段具有以下结构

pubspec.yaml

yaml

flutter:
  assets:
    - [ path_to_file | path_to_directory ]
      [ flavor_path_field | platform_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

yaml

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

您可以传入文件路径

pubspec.yaml

yaml

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

您可以传入目录路径

pubspec.yaml

yaml

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

您可以传入特定 flavor 的目录路径

pubspec.yaml

yaml

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

您可以传入特定平台的文件的路径

pubspec.yaml

yaml

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

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

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

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

pubspec.yaml

yaml

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

使用 flutter config --help 获取每个标志的描述。

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

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

pubspec.yaml

yaml

flutter:
  default-flavor: flavor_name

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

pubspec.yaml

yaml

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 字段具有以下结构

pubspec.yaml

yaml

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

延迟组件子字段

name：特定延迟组件的唯一标识符。
libraries：延迟组件中包含的 Dart 库列表。
assets：与延迟组件关联的资产路径列表。

示例

pubspec.yaml

yaml

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 包管理器 (SPM) 的使用，使其不再管理 iOS 和 macOS Flutter 项目中的依赖项。

pubspec.yaml

yaml

flutter:
  disable-swift-package-manager: true

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

一个包含应用程序特定 Flutter 设置的字段。

pubspec.yaml

yaml

flutter:
  [flutter_field]
  [...]

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

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

fonts 字段具有以下结构

pubspec.yaml

yaml

flutter:
  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

yaml

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

使用字体系列

pubspec.yaml

yaml

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

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

pubspec.yaml

yaml

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

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

启用通用本地化

pubspec.yaml

yaml

flutter:
  generate: true

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

licenses 字段具有以下结构

pubspec.yaml

yaml

flutter:
  licenses:
    - [path_to_file]

配置 Flutter 插件的特定设置。

plugin 字段具有以下结构

pubspec.yaml

yaml

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 包名称。可以与 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 文件中的 shaders 部分中声明。Flutter 命令行工具会将着色器编译为其适当的后端格式，并生成其必要的运行时元数据。然后，编译后的着色器就像资产一样包含在应用程序中。

shaders 字段具有以下结构

pubspec.yaml

yaml

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

yaml

# path_to_file structure
- assets/shaders/file

yaml

# path_to_directory structure
- assets/shaders/

添加特定的着色器

pubspec.yaml

yaml

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

添加着色器目录

pubspec.yaml

yaml

flutter:
  shaders:
    - assets/shaders/

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

pubspec.yaml

yaml

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

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

pubspec.yaml

yaml

flutter:
  uses-material-design: true

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

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

pubspec.yaml

yaml

dependencies:
  flutter:
    sdk: flutter

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

pubspec.yaml

yaml

dependencies:
  flutter_localizations:
    sdk: flutter
  intl: any

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

pubspec.yaml

yaml

dependencies:
  flutter_test:
    sdk: flutter

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

pubspec.yaml

yaml

dev_dependencies:
  flutter_lints: ^6.0.0

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

pubspec.yaml

yaml

dependencies:
  cupertino_icons: ^1.0.0

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

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

此页面内容有帮助吗？

除非另有说明，此网站上的文档反映了 Flutter 3.38.6。页面上次更新于 2026-02-09。查看源代码或报告问题。

Flutter pubspec 选项

概述

示例

字段

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

更多信息