使用編譯環境宣告配置應用

在構建或執行 Dart 應用時，你可以指定編譯環境宣告。編譯環境宣告以鍵值對的形式指定配置選項，這些選項在編譯時被訪問和評估。

你的應用可以使用環境宣告的值來改變其功能或行為。Dart 編譯器可以根據環境宣告的值，消除因控制流而無法到達的程式碼。

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

• 在除錯期間新增功能，例如啟用日誌記錄。
• 為你的應用建立不同的“風格”（flavors）。
• 配置應用行為，例如 HTTP 伺服器的埠。
• 為測試啟用應用的實驗模式。
• 在測試後端和生產後端之間切換。

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

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

要了解如何使用其他工具設定這些宣告，請查閱本指南中的指定環境宣告部分。該部分解釋了宣告語法以及如何在命令列、IDE 和編輯器中指定它們。

要訪問指定的環境宣告值，請使用其中一個 fromEnvironment 建構函式，並結合 const 或在常量上下文中使用。對於 true 或 false 值，使用 bool.fromEnvironment；對於整數值，使用 int.fromEnvironment；對於其他任何值，使用 String.fromEnvironment。

每個 fromEnvironment 建構函式都需要環境宣告的名稱或鍵。它們還接受一個可選的 defaultValue 命名引數來覆蓋預設的回退值。當宣告未定義或指定的值無法解析為預期型別時，將使用預設的回退值。

例如，如果你只想在環境宣告 DEBUG 設定為 true 時列印日誌訊息

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 建構函式

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

dart run 和 dart 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 以將環境宣告傳遞給開發和生產 Web 編譯器，請查閱webdev 配置文件。

在啟動配置 (launch.json) 的 configurations 下，新增一個新的 toolArgs 鍵，其中包含你想要的環境宣告。

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

要了解更多資訊，請查閱 VS Code 啟動配置的文件。

在專案的執行/除錯配置中，將你想要的環境宣告新增到 VM options 中。

要了解更多資訊，請查閱 JetBrains 關於 Dart 執行/除錯配置的文件。

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

flutter run --dart-define=DEBUG=true