Flutter pubspec 選項

介紹 pubspec 檔案中僅限 Flutter 使用的欄位。

本頁面主要面向 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

yaml

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

publish_to: none
version: 1.0.0+1

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

除了列出包含在應用包中的影像外，影像資源還可以引用一個或多個特定解析度的“變體”。有關更多資訊，請參閱資源和影像頁面中的解析度感知部分。有關從軟體包依賴項新增資源的資訊，請參閱同一頁面中的軟體包依賴項中的資源影像部分。

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 structure
- 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 變體列表。要了解有關變體的更多資訊，請參閱設定 iOS 和 macOS 的變體以及設定 Android 的變體。
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/

您可以為特定變體傳入目錄路徑

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 變體。使用此項時，無需在 Flutter 啟動命令中包含此變體的名稱。

pubspec.yaml

yaml

flutter:
  default-flavor: flavor_name

在以下示例中，Android Flutter 應用具有名為 staging 和 production 的變體。production 是預設變體。執行該變體時，無需在啟動命令中指定它。

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 變體，請參閱設定 Android 的 Flutter 變體和設定 iOS 和 macOS 的 Flutter 變體。

推遲 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 Package Manager (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 應用的單元測試、小部件測試或整合測試，請使用此項。

pubspec.yaml

yaml

dependencies:
  flutter_test:
    sdk: flutter

為 Flutter 專案提供一系列推薦 Lint 規則的軟體包。此軟體包可以新增到 pubspec 的 dev_dependency 欄位中。

pubspec.yaml

yaml

dev_dependencies:
  flutter_lints: ^6.0.0

為 Flutter 應用程式提供一系列 Apple Cupertino 圖示的軟體包。此軟體包可以新增到 pubspec 的 dependency 欄位中。

pubspec.yaml

yaml

dependencies:
  cupertino_icons: ^1.0.0

有關軟體包、外掛和 pubspec 檔案的更多資訊，請參閱以下內容：

dart.dev 上的建立軟體包
dart.dev 上的軟體包術語表
dart.dev 上的軟體包依賴項
使用軟體包
dart.dev 上的不應提交的內容

此頁面內容有幫助嗎？

除非另有說明，本網站上的文件反映了 Flutter 3.41.5 的內容。頁面最後更新於 2026-05-11。檢視原始碼或報告問題。

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 軟體包

更多資訊