コンパイル環境宣言によるアプリの設定

Dart アプリケーションのビルドまたは実行時に、コンパイル環境宣言を指定できます。コンパイル環境宣言は、コンパイル時にアクセスおよび評価されるキーと値のペアとして構成オプションを指定します。

アプリは、環境宣言の値を使用して、その機能や動作を変更できます。Dart コンパイラは、環境宣言の値を使用した制御フローによって到達不能になったコードを削除できます。

環境宣言を定義して使用すると、次のことが可能になります。

• デバッグ中に、ロギングを有効にするなどの機能を追加する。
• アプリケーションの個別のフレーバーを作成する。
• HTTP サーバーのポートなど、アプリケーションの動作を構成する。
• テストのために、アプリケーションの実験的なモードを有効にする。
• テスト用と本番用のバックエンドを切り替える。

Dart アプリケーションの実行またはコンパイル時に環境宣言を指定するには、--define オプションまたはその省略形である -D を使用します。<NAME>=<VALUE> の形式で宣言のキーと値のペアを指定します。

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

他のツールでこれらの宣言を設定する方法については、このガイドの「環境宣言の指定」セクションを参照してください。このセクションでは、宣言の構文と、コマンドライン、IDE、エディターでそれらを指定する方法について説明します。

指定された環境宣言の値にアクセスするには、`const` を使用した、または定数コンテキスト内の `fromEnvironment` コンストラクタのいずれかを使用します。`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 オプションに目的の環境宣言を追加します。

詳細については、JetBrains の Dart 実行/デバッグ構成 のドキュメントを参照してください。

Flutter ツールに環境宣言を指定するには、代わりに --dart-define オプションを使用します。

flutter run --dart-define=DEBUG=true