Flutter pubspec 選項
說明 pubspec 檔案中僅限 Flutter 使用的欄位。
每個以 Dart 語言撰寫的專案,包括所有 Flutter 應用程式與程式庫,都包含一個 pubspec.yaml 檔案,稱為 pubspec。建立新專案時,系統會在專案樹的最上層產生一個基本的 pubspec,其中包含中繼資料並列出專案的相依套件。
Dart 與 Flutter 專案都通用的欄位,請參考 dart.dev 上的 pubspec 檔案。 本頁列出僅適用於 Flutter 專案的欄位。
範例
#當你使用 flutter create 指令(或在你的 IDE 中使用對應的按鈕)建立新專案時,系統會為基本的 Flutter 應用程式建立一個 pubspec。
第一次建置專案時,系統也會建立一個 pubspec.lock 檔案,裡面記錄了所包含套件的特定版本。這可確保下次建置專案時,取得相同的套件版本。
若想進一步了解 Flutter 與 Dart 如何解析套件相依性,請參閱 Package dependency management。
以下的 pubspec 檔案範例標示出僅在 Flutter 應用程式中使用的欄位。 其他未標示的欄位,請參閱 dart.dev。
name: <project name>
description: A new Flutter project.
publish_to: 'none' # Remove this line if you wish to publish to pub.dev
version: 1.0.0+1
environment:
sdk: ^3.13.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
material_ui # Required for projects that use the Material components pkg
cupertino_ui # Required for projects that use the Cupertino components pkg
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
integration_test:
sdk: flutter # Required for integration 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.jpeg
- images/a_dot_ham.jpeg
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 欄位。 若想了解一般的 Dart 欄位,請參閱 Dart's pubspec supported fields。
assets 欄位
#
您的應用程式所使用的資源(assets)路徑清單。這些資源會與您的應用程式一起打包。常見的資源類型包括靜態資料(例如:JSON)、設定檔、圖示,以及圖片(JPEG、WebP、GIF、動畫
WebP/GIF、PNG、BMP 及 WBMP)。
除了列出包含於應用程式套件中的圖片外,圖片資源也可以指向一個或多個針對不同解析度的「變體」。如需更多資訊,請造訪 resolution aware 章節以及 Assets and images 頁面。 若要了解如何從套件相依性中加入資源,請造訪同一頁的 asset images in package dependencies 章節。
assets 欄位的結構如下:
flutter:
assets:
- [ path_to_file | path_to_directory ]
[ flavor_path_field | platform_path_field | transformer_path_field ]
[...]
# path_to_file structure
- path/to/directory/file
# path_to_directory structure
- path/to/directory/
# flavor_path_field structure
- path: path/to/directory
flavors:
- flavor_name
# platform_path_field structure
- path: path/to/file
platforms:
- platform_name
# transformer_path_field structure
- path: path/to/file
transformers:
- package: transformer_package_name
args: ['arg1', 'arg2'] # Optional
assets 的子欄位:
path_to_file:代表檔案路徑的字串。path_to_directory:代表目錄路徑的字串。flavor_path_field:一個路徑欄位及其 flavor 子欄位。platform_path_field:一個路徑欄位及其平台子欄位。transformer_path_field:一個路徑欄位及其轉換器(transformer)子欄位。path:資源檔案或目錄的路徑。-
flavors:在特定路徑下要搭配資源(assets)使用的 Flutter flavor 清單。若要進一步了解 flavor,請參閱設定 flavor 的指南:Android、iOS and macOS、Linux 與 Windows。 -
platforms:在特定路徑下要搭配資源使用的平台清單。有效值為android、ios、web、linux、macos及windows。 -
transformers:在建置時要對資源執行的轉換器套件清單。若要進一步了解,請參閱 Transforming assets at build time。
你可以傳入檔案的路徑:
flutter:
assets:
- assets/images/my_image_a.png
- assets/images/my_image_b.png
你可以傳入一個目錄的路徑:
flutter:
assets:
- assets/images/
- assets/icons/
你可以針對特定的 flavor 傳入一個目錄的路徑:
flutter:
assets:
- path: assets/flavor_a_and_b/images
flavors:
- flavor_a
- flavor_b
- path: assets/flavor_c/images
flavors:
- flavor_c
你可以針對特定平台傳入一個檔案的路徑:
flutter:
assets:
- path: assets/web_worker.js
platforms:
- web
- path: assets/desktop_icon.png
platforms:
- windows
- linux
- macos
你可以設定建置時的資源轉換器:
flutter:
assets:
- path: assets/logo.svg
transformers:
- package: vector_graphics_compiler
args: ['--tessellate']
config 欄位
#
這是一個鍵值對應的 map,將鍵對應到旗標(true 或 false),用來影響 flutter 命令列介面(Command Line Interface)的執行方式。
可用的鍵與 flutter config --list 中可用的鍵相同。
flutter:
config:
cli-animations: false
使用 flutter config --help 來查看每個 flag 的說明。
flag 只會從目前的 應用程式 套件中讀取,在套件或相依套件的情境下不會產生任何效果。
enable-swift-package-manager 欄位
#
控制 Flutter 是否使用 Swift Package Manager 來管理此專案的原生 iOS 與 macOS 相依性。
若要在此專案中停用,請將此欄位設為 false。
flutter:
config:
enable-swift-package-manager: false
default-flavor 欄位
#為應用程式指定預設的 Flutter flavor。 當設定此欄位後,在啟動 Flutter 時就不需要在指令中額外包含這個 flavor 的名稱。
flutter:
default-flavor: flavor_name
在以下範例中,一個 Android Flutter 應用程式有名為 staging 和 production 的 flavor。production
flavor 是預設的 flavor。當執行該 flavor 時,你不需要在啟動指令中額外指定它。
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 flavors,請參閱設定 flavor 的指南: Android、iOS and macOS、Linux 與 Windows。
deferred-components 欄位
#延後下載元件,以縮減 Android 應用程式的初始下載大小。這通常用於大型應用程式、模組化應用程式,以及具有隨需功能的應用程式。
deferred-components 欄位的結構如下:
flutter:
deferred-components:
- name: component_name
libraries:
- string_expression
[...]
assets:
- string_expression
[...]
[...]
延遲元件(deferred component)子欄位:
name:特定延遲元件的唯一識別碼。libraries:屬於該延遲元件的 Dart 程式庫清單。assets:與該延遲元件相關聯的資源(assets)路徑清單。
範例:
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 應用程式中使用延遲元件(deferred components),請參閱 Deferred components for Android。
flutter 欄位
#一個包含 Flutter 專屬設定的欄位,適用於您的應用程式。
flutter:
[flutter_field]
[...]
fonts 欄位
#在你的 Flutter 應用程式中設定並加入自訂字型(custom fonts)。
關於使用字型的範例,請造訪 Flutter cookbook 中的 Use a custom font 以及 Export fonts from a package 教學。
fonts 欄位的結構如下:
flutter:
fonts:
- { font_family_field | font_asset_field }
[...]
# font_family_field structure
- family: font_name
fonts:
- font_asset_field
[...]
# 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。
使用不屬於字型家族的字型:
flutter:
fonts:
- asset: fonts/Roboto-Regular.ttf
weight: 900 # Optional
style: italic # Optional
使用字型家族(font family):
flutter:
fonts:
- family: Roboto # Optional
fonts:
- asset: fonts/Roboto-Regular.ttf
- asset: fonts/Roboto-Bold.ttf
weight: 700 # Optional
style: italic # Optional
或者,如果你有一個字型(font)不需要指定 family、weight 或 style,你可以將它作為一個簡單的資源(asset)宣告:
flutter:
assets:
- fonts/Roboto-Regular.ttf
generate 欄位
#啟用從 .arb 檔案產生包含在地化字串的 Dart 檔案。
啟用一般在地化功能:
flutter:
generate: true
若想進一步了解,請造訪 Internationalizing Flutter apps。
licenses 欄位
#一個額外授權檔案路徑的清單,這些檔案會與您的應用程式一起打包。這些檔案通常位於您專案的 assets 目錄中。
licenses 欄位的結構如下:
flutter:
licenses:
- [path_to_file]
module 欄位
#在將 Flutter 加入既有的 Android 或 iOS 宿主應用程式(Add-to-App)時,設定 Flutter module 專案的相關設定。
module 欄位的結構如下:
flutter:
module:
androidPackage: com.example.my_module # Optional
iosBundleIdentifier: com.example.myModule # Optional
module 的子欄位:
androidX:選填。指定此 module 是否使用 AndroidX。androidPackage:選填。用於產生的 Android 程式碼的套件名稱。iosBundleIdentifier:選填。用於產生的 iOS 程式碼的 bundle identifier。
若想進一步了解,請造訪 Add Flutter to existing apps。
plugin 欄位
#專門用於設定 Flutter 外掛(plugin)的相關設定。
plugin 欄位的結構如下:
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:選填。指定作為平台介面預設實作的套件。僅適用於聯邦式外掛(federated plugins),即外掛的實作分為多個特定平台的套件時。dartPluginClass:選填。作為 Flutter 外掛進入點的 Dart 類別。這可用於 Android、iOS、Linux、macOS 和 Windows 平台。sharedDarwinSource:選填。表示該外掛在 iOS 與 macOS 之間共用原生程式碼。這可用於 iOS 和 macOS 平台。fileName:選填。包含外掛類別的檔案。ffiPlugin:選填。如果外掛使用 Foreign Function Interface (FFI),則為 true。implements:選填。Flutter 外掛所實作的平台介面。
如需進一步了解外掛,請參閱 Developing packages & plugins。
shaders 欄位
#
具有 .frag 副檔名的 GLSL 著色器(shaders),必須在專案的 pubspec.yaml 檔案的 shaders
區段中宣告。
Flutter 命令列工具會將著色器編譯為對應後端格式並產生必要的執行時中繼資料。編譯後的著色器會像資源(asset)一樣被包含在應用程式中。
shaders 欄位接受個別檔案路徑的清單,不支援目錄路徑。
此欄位的結構如下:
flutter:
shaders:
- [path_to_file]
[...]
例如,要在專案中新增特定著色器:
flutter:
shaders:
- assets/shaders/shader_a.frag
- assets/shaders/shader_b.frag
請勿將著色器檔案列在 assets 欄位下,無論是直接列出或透過包含它們的目錄。
如果著色器同時在兩處宣告,Flutter 工具會回報錯誤。
與其他資源一樣,著色器也支援 flavors、platforms 與 transformers。
若想進一步了解如何在 Flutter 中使用著色器,請參閱 Writing and using fragment shaders。
uses-material-design 欄位
#在您的 Flutter 應用程式中使用 Material Design 元件 (Material components) 與圖示字型。
flutter:
uses-material-design: true
套件(Packages)
#以下這些 Flutter 專用套件可以加入到 pubspec 中。如果你新增了套件,請在終端機執行 flutter pub get 來安裝該套件。
flutter 套件
#
這是一個代表 Flutter SDK(Flutter 軟體開發套件)本身的套件,可以加入到 dependencies 欄位。如果你的專案依賴於 Flutter SDK,而不是來自 pub.dev 的一般套件,請使用這個設定。
dependencies:
flutter:
sdk: flutter
flutter_localizations 套件
#由 Flutter SDK 提供的套件,可啟用 ARB 檔案的在地化功能。通常會與 intl 套件搭配使用。
dependencies:
flutter_localizations:
sdk: flutter
intl: any
flutter_test 套件
#由 Flutter SDK 提供的套件,包含用於 Flutter 應用程式單元測試與元件(Widget)測試的測試工具。
dev_dependencies:
flutter_test:
sdk: flutter
integration_test 套件
#由 Flutter SDK 提供的套件,用於在目標裝置或模擬器上執行整合測試。
dev_dependencies:
integration_test:
sdk: flutter
若想進一步了解,請造訪 Integration testing。
flutter_lints 套件
#一個為 Flutter 專案提供建議檢查規則(lints)集合的套件。你可以將此套件加入 pubspec 的 dev_dependencies 欄位中。
dev_dependencies:
flutter_lints: ^6.0.0
cupertino_icons 套件
#
這是一個提供 Apple 的 Cupertino 圖示(icons)套件,可用於 Flutter 應用程式中。你可以將此套件加入到 pubspec 的 dependencies
欄位中。
dependencies:
cupertino_icons: ^1.0.8
更多資訊
#若需瞭解有關套件(packages)、外掛(plugins)及 pubspec 檔案的更多資訊,請造訪以下內容:
- Add Flutter to existing apps
- Creating packages(在 dart.dev 上)
- Glossary of package terms(在 dart.dev 上)
- Integration testing
- Package dependency management
- Package dependencies(在 dart.dev 上)
- 設定 Android 的 Flutter flavors
- 設定 iOS 與 macOS 的 Flutter flavors
- 設定 Linux 的 Flutter flavors
- 設定 Windows 的 Flutter flavors
- Transforming assets at build time
- Using packages
- What not to commit(在 dart.dev 上)
Unless stated otherwise, the documentation on this site reflects Flutter 3.47. Page last updated on 2026-10-25. View source or report an issue.