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

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

開発用および本番用 Web コンパイラの両方に環境宣言を渡すように webdev を構成する方法については、webdev 構成ドキュメントを参照してください。

configurations の下の起動構成 (launch.json) に、目的の環境宣言を含む新しい 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

特に明記されていない限り、このサイトのドキュメントは Dart 3.5.3 を反映しています。ページの最終更新日は 2024-07-03 です。 ソースを表示 または 問題を報告する。