Flutter环境变量管理插件env_flutter的使用

Flutter环境变量管理插件env_flutter的使用

env_flutter 插件用于在运行时从 .env 文件加载配置，并可以在整个应用程序中使用这些配置。

关于

该库是 java-james/flutter_dotenv 的一个分支，稍作修改以支持不同阶段的 .env 文件读取。

环境变量是在进程中已知的一组变量（如 PATH、PORT 等）。通过从文件中读取这些值，可以模拟生产环境进行开发（测试、预发布等）。

此库解析该文件，并将其值与内置的 Platform.environment 映射合并。

使用

1. 创建 .env 文件

在项目的根目录下创建一个 .env 文件，包含示例内容：

FOO=foo
BAR=bar
FOOBAR=$FOO$BAR
ESCAPED_DOLLAR_SIGN='$1000'
# 这是一个注释

注意：如果部署到 Web 服务器，请确保配置文件已上传且未被忽略。（在服务器上将配置文件列入白名单，或者将配置文件命名为不带前导 . 的名称。）

2. 将 .env 文件添加到资源包中

在 pubspec.yaml 文件中添加所有 .env 文件到资源包：

assets:
  - .env
  - .env.development
  - .env.production
  - .env.test
  - .env.local
  - .env.development.local
  - .env.production.local
  - .env.test.local

确保路径与步骤1和步骤2中的路径相对应。

3. 将 .env 文件添加到 .gitignore

在 .gitignore 文件中添加以下内容以防止将 .env 文件纳入版本控制：

*.env

4. 在 main.dart 中加载 .env 文件

在 main.dart 文件中导入并加载 .env 文件：

import 'package:env_flutter/env_flutter.dart';

Future<void> main() async {
  // 加载 .env 文件内容到 env。
  // 注意：fileName 默认为 .env，可以在此省略。
  // 确保文件名与第1步和第2步中的路径相对应。
  await dotenv.load(fileName: 'assets/.env');
  
  runApp(MyApp());
}

你可以通过以下方式在整个应用中访问 .env 文件中的变量：

import 'package:env_flutter/env_flutter.dart';

String foo = dotenv.env['FOO'];

你也可以将 env 映射到一个配置模型来按类型访问配置。

其他可使用的 .env 文件

• .env: 默认。
• .env.local: 本地覆盖。此文件在所有环境中加载，除了测试。
• .env.development, .env.test, .env.production: 环境特定设置。
• .env.development.local, .env.test.local, .env.production.local: 环境特定设置的本地覆盖。

文件优先级：

• flutter run: .env.development.local, .env.local, .env.development, .env
• npm build: .env.production.local, .env.local, .env.production, .env
• flutter test: .env.test.local, .env.test, .env （注意 .env.local 被忽略了）

高级用法

引用

你可以在 .env 文件中引用其他定义的变量：

FOO=foo
BAR=bar
FOOBAR=$FOO$BAR

可以通过包裹值在单引号中来转义引用：

ESCAPED_DOLLAR_SIGN='$1000'

合并

你可以在加载时合并一个映射：

await DotEnv.load(mergeWith: { "FOO": "foo", "BAR": "bar" });

你也可以在 .env 文件中引用这些合并的变量：

FOOBAR=$FOO$BAR

测试中使用

有一个 testLoad 方法可以用来加载静态变量集用于测试：

// 从静态字符串加载。
dotenv.testLoad(fileInput: '''FOO=foo
BAR=bar
''');

// 从文件同步加载。
dotenv.testLoad(fileInput: File('test/.env').readAsStringSync());

防止空安全检查

为了避免对不存在的变量进行空安全检查，可以使用 get() 方法，该方法会在变量未定义时抛出异常。你还可以指定一个默认回退值，当变量在 .env 文件中未定义时使用：

Future<void> main() async {
  await dotenv.load();

  String foo = dotenv.get('VAR_NAME');

  // 或者使用回退值。
  String bar = dotenv.get('MISSING_VAR_NAME', fallback: 'sane-default');

  // 这将返回 null。
  String? baz = dotenv.maybeGet('MISSING_VAR_NAME', fallback: null);
}

使用平台环境

你可以将 Platform.environment 映射合并到 env 中：

// 例如使用包含 CLIENT_ID 条目的 Platform.environment
await DotEnv.load(mergeWith: Platform.environment);
print(env["CLIENT_ID"]);

像上面描述的其他合并条目一样，.env 条目可以引用这些合并的 Platform.Environment 条目：

CLIENT_URL=https://$CLIENT_ID.dev.domain.com

讨论

使用 问题跟踪器 报告错误和功能请求。

欢迎提交拉取请求。

许可证

MIT许可证

完整示例代码

import 'package:env_flutter/env_flutter.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

Future<void> main() async {
  await dotenv.load(
    fileNames: [
      'assets/.env',
      'assets/.env.production',
      'assets/.env.production.europe-stage',
    ],
    mergeWith: {
      'TEST_VAR': '5',
    },
  ); // mergeWith 可选，你可以包括 Platform.environment 供移动/桌面应用使用

  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Dotenv Demo',
      home: Scaffold(
        appBar: AppBar(
          title: Text('Dotenv Demo'),
        ),
        body: SingleChildScrollView(
          child: FutureBuilder<String>(
            future: rootBundle.loadString('assets/.env'),
            initialData: '',
            builder: (context, snapshot) => Container(
              padding: EdgeInsets.all(50),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text('Env map:'),
                  Divider(thickness: 1),
                  _buildEnvEntries(),
                ],
              ),
            ),
          ),
        ),
      ),
    );
  }

  Widget _buildEnvEntries() {
    return Column(
      children: dotenv.env.entries
          .map(
            (entry) => Padding(
              padding: const EdgeInsets.all(2),
              child: Row(
                children: [
                  Container(
                    padding: const EdgeInsets.all(2),
                    child: Text('${entry.key} = '),
                  ),
                  Container(
                    padding: const EdgeInsets.all(2),
                    color: Colors.amberAccent,
                    child: Text(entry.value),
                  ),
                ],
              ),
            ),
          )
          .toList(),
    );
  }
}