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

更多資訊