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

更多資訊