內容

使用編譯環境宣告設定應用程式

您可以在建立或執行 Dart 應用程式時指定編譯環境宣告。編譯環境宣告會以鍵值對的形式指定設定選項,並在編譯時存取和評估。

您的應用程式可以使用環境宣告的值來變更其功能或行為。Dart 編譯器可以使用環境宣告值來消除因控制流程而無法存取的程式碼。

您可以定義和使用環境宣告來

  • 在除錯期間新增功能,例如啟用記錄。
  • 建立應用程式的不同版本。
  • 設定應用程式行為,例如 HTTP 伺服器的連接埠。
  • 啟用應用程式的實驗模式以進行測試。
  • 在測試和生產後端之間切換。

要在執行或編譯 Dart 應用程式時指定環境宣告,請使用 --define 選項或其縮寫 -D。使用 <NAME>=<VALUE> 格式指定宣告鍵值對

$ dart run --define=DEBUG=true -DFLAVOR=free

若要了解如何使用其他工具設定這些宣告,請查看本指南中的 指定環境宣告 區段。該區段說明宣告語法,以及如何在命令列和 IDE 及編輯器中指定宣告。

存取環境宣告

#

若要存取指定的環境宣告值,請使用其中一個 fromEnvironment 建構函式,並搭配 const 或在常數內容中使用。對於 truefalse 值,請使用 bool.fromEnvironment;對於整數值,請使用 int.fromEnvironment;對於其他任何值,請使用 String.fromEnvironment

每個 fromEnvironment 建構函式都需要環境宣告的名稱或金鑰。它們也接受一個選用的 defaultValue 名稱參數,用於覆寫預設的後備值。當宣告未定義或指定的數值無法解析為預期的類型時,會使用預設的後備值。

例如,如果您只想在環境宣告 DEBUG 設為 true 時列印記錄訊息

dart
void log(String message) {
  // Log the debug message if the environment declaration 'DEBUG' is `true`.
  // If there was no value specified, do not log.
  if (const bool.fromEnvironment('DEBUG', defaultValue: false)) {
    print('Debug: $message');
  }
}

在此程式片段中,如果在編譯期間將 DEBUG 設為 false,或根本未指定,生產編譯器可以完全移除條件及其主體。

當宣告未指定或指定的數值無法解析時,fromEnvironment 建構函式會後備為預設值。因此,若要特別檢查環境宣告是否已指定,請使用 bool.hasEnvironment 建構函式

dart
if (const bool.hasEnvironment('DEBUG')) {
  print('Debug behavior was configured!');
}

指定環境宣告

#

Dart CLI

#

dart rundart compile 子指令都接受任意數量的 -D--define 選項,用於指定環境宣告值。

$ dart run --define=DEBUG=true -DFLAVOR=free main.dart
$ dart compile exe --define=DEBUG=true -DFLAVOR=free main.dart
$ dart compile js --define=DEBUG=true -DFLAVOR=free main.dart
$ dart compile aot-snapshot --define=DEBUG=true -DFLAVOR=free main.dart
$ dart compile jit-snapshot --define=DEBUG=true -DFLAVOR=free main.dart
$ dart compile kernel --define=DEBUG=true -DFLAVOR=free main.dart

webdev

#

若要了解如何設定 webdev 以將環境宣告傳遞給開發和生產網路編譯器,請查看 webdev 設定文件

Visual Studio Code

#

configurations 下的啟動設定 (launch.json) 中,新增一個包含您所需環境宣告的新 toolArgs 金鑰

json
"configurations": [
    {
        "name": "Dart",
        "request": "launch",
        "type": "dart",
        "toolArgs": [
          "--define=DEBUG=true"
        ]
    }
]

若要深入了解,請查看 VS Code 啟動設定 的文件。

JetBrains IDE

#

在專案的執行/偵錯設定中,將您所需的環境宣告新增至VM 選項

Adding define option to Jetbrains IDE

若要深入了解,請查看 JetBrains 的 Dart 執行/偵錯設定 文件。

Flutter

#

若要向 Flutter 工具指定環境宣告,請改用 --dart-define 選項

$ flutter run --dart-define=DEBUG=true