使用编译环境声明配置应用

访问环境声明
指定环境声明

构建或运行 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 时打印日志消息：

dartvoid log(String message) {
  // 如果环境声明 'DEBUG' 为 `true` ，则记录调试消息。
  // 如果没有指定值，则不记录日志。
  if (const bool.fromEnvironment('DEBUG', defaultValue: false)) {
    print('Debug: $message');
  }
}

在此代码段中，如果在编译期间 DEBUG 设置为 false 或根本未指定，则生产编译器可以完全删除条件及其主体。

当未指定声明或无法解析指定值时， fromEnvironment 构造函数将回退到默认值。因此，要专门检查是否已指定环境声明，请使用 bool.hasEnvironment 构造函数：

dartif (const bool.hasEnvironment('DEBUG')) {
  print('已配置调试行为！');
}

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 键，其中包含所需的環境声明：

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

要了解更多信息，请查看 VS Code 启动配置文档。

在项目的 运行/调试配置 中，将所需的環境声明添加到 VM 选项 ：

将 define 选项添加到 Jetbrains IDE

要了解更多信息，请查看 JetBrains 的 Dart 运行/调试配置文档。

要向 Flutter 工具指定环境声明，请使用 --dart-define 选项：

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

除非另有说明，否则本网站上的文档反映的是 Dart 3.6.0。页面最后更新于 2025-02-05。查看源代码或报告问题.

使用编译环境声明配置应用

访问环境声明

指定环境声明

Dart CLI

`webdev`

Visual Studio Code

JetBrains IDEs

Flutter