搜索插件、代码仓与 APP 分类

插件详情v6.0.2

flutter_dotenv

使用 .env 文件轻松配置任何 Flutter 应用程序的全局变量。

AndroidiOSWebmacOSWindowsLinux
近 30 天下载
101万
喜欢数
2250
Pub 分数
160

安装插件

flutter pub add flutter_dotenv

插件介绍

基于插件公开信息、社区数据与项目使用情况整理的选型参考。

flutter_dotenv 是一个 Flutter 包,允许开发者使用 .env 文件在其应用程序中管理环境变量。它通过在运行时从文件加载键值对来简化配置,从而轻松处理开发、测试和生产环境中的不同设置。该包支持所有主要平台,包括 Android、iOS、Web、macOS、Windows 和 Linux。它可以通过简单的 pub add 命令与 Flutter 项目无缝集成。

适合场景

  • 安全地管理API密钥
  • 在开发和生产配置之间切换
  • 存储敏感凭据
  • 按环境自定义应用行为
  • 启用功能标志
  • 避免硬编码值

主要特点

  • 简单的 .env 文件集成
  • 跨平台支持
  • 运行时变量加载
  • 通过 pub add 实现快速设置
  • 支持环境特定的变量
  • 最小化样板代码

适合对象

  • 开发人员管理多个环境
  • 需要安全配置管理的团队
  • 需要动态配置的应用程序
  • 使用 CI/CD 流水线的项目
  • 前端开发人员与后端API协作
  • 使用可配置设置进行原型设计

使用建议

  • 永远不要将 .env 文件提交到版本控制中
  • 确保 .env 文件包含在构建过程中
  • 对于高度敏感的数据请谨慎使用
  • 验证不同部署场景中的文件路径
  • 优雅地处理缺失的变量
  • 注意变量名的大小写敏感性

原始 README

以下为关联源码仓库的 README 原文快照,最新内容请访问源码仓库。

flutter_dotenv

Pub Version License: MIT

Load configuration into your Flutter app from a .env asset file or string.

Install

flutter pub add flutter_dotenv

Quick start

1. Create a .env file in your project root:

API_URL=https://api.example.com
MAX_RETRIES=3
DEBUG=true

2. Register it as an asset in pubspec.yaml:

flutter:
  assets:
    - .env

3. Load and use:

import 'package:flutter_dotenv/flutter_dotenv.dart';

Future<void> main() async {
  await dotenv.load();
  runApp(const MyApp());
}

After loading, access values anywhere you import the package:

import 'package:flutter_dotenv/flutter_dotenv.dart';

// Inside a function, widget, or service — not as a top-level initializer
final apiUrl = dotenv.get('API_URL');
final retries = dotenv.getInt('MAX_RETRIES', fallback: 1);
final debug = dotenv.getBool('DEBUG', fallback: false);

If your .env file is in a subdirectory (e.g. assets/.env), pass fileName: 'assets/.env' to load() and register the same path in pubspec.yaml.

You do not need to call WidgetsFlutterBinding.ensureInitialized() — the library handles this internally when loading assets.

Tip: Add .env and any environment-specific variants (e.g. .env.staging) to your .gitignore if they should not be committed.

Security

Do not store secrets (API keys, tokens, passwords) in your .env file. Flutter assets are bundled into the app binary and can be extracted by anyone with access to the build. Values loaded by this package should be treated as public client-side configuration.

Use .env files for non-sensitive configuration only — API base URLs, feature flags, timeout values, and similar settings.

For guidance on securing sensitive data, see the OWASP Mobile Top 10.

Reading variables

The package exports a singleton instance named dotenv. Accessing any variable before calling load() or loadFromString() throws NotInitializedError.

Use get() for required values, maybeGet() for optional values, and env[...] when direct map access is preferred.

Method Returns When missing
dotenv.env['NAME'] String? null
dotenv.get('NAME') String Throws AssertionError
dotenv.get('NAME', fallback: 'x') String 'x'
dotenv.maybeGet('NAME') String? null
dotenv.maybeGet('NAME', fallback: 'x') String? 'x'

dotenv.env exposes the loaded key-value map directly. Treat it as read-only.

Typed getters

Parse values directly as int, double, or bool:

final retries = dotenv.getInt('MAX_RETRIES', fallback: 3);
final rate    = dotenv.getDouble('RATE', fallback: 0.5);
final debug   = dotenv.getBool('DEBUG', fallback: false);

All typed getters throw AssertionError if the variable is missing and no fallback is provided, and FormatException if the value cannot be parsed. getBool recognises true, false, 1, and 0 (case-insensitive).

Validating required variables
const required = ['API_URL', 'MAX_RETRIES'];
if (!dotenv.isEveryDefined(required)) {
  throw Exception('Missing required env variables');
}

isEveryDefined() returns true only when every listed variable exists with a non-empty value.

Loading

load()

Load variables from a .env asset file:

await dotenv.load(
  fileName: '.env',
  overrideWithFiles: ['.env.staging'],
  mergeWith: {'BUILD': 'ci'},
  isOptional: false,
);
Parameter Type Default Description
fileName String '.env' Asset path of the env file (must match pubspec.yaml).
overrideWithFiles List<String> [] Additional env asset files that override the base file.
mergeWith Map<String, String> {} Programmatic key-value pairs (highest precedence).
isOptional bool false When true, missing or empty files don't throw.
parser Parser Parser() Custom parser instance.

When isOptional is true, FileNotFoundError and EmptyEnvFileError are suppressed.

loadFromString()

Load variables from a string — useful for tests or in-memory configuration:

dotenv.loadFromString(envString: 'FOO=bar\nBAZ=qux');
Parameter Type Default Description
envString String '' The env-formatted string to parse.
overrideWith List<String> [] Additional env strings that override the base string.
mergeWith Map<String, String> {} Programmatic key-value pairs (highest precedence).
isOptional bool false When true, an empty string doesn't throw.
parser Parser Parser() Custom parser instance.

When isOptional is true, EmptyEnvFileError is suppressed.

Value precedence

Both load() and loadFromString() call clean() first, replacing any previously loaded state. The parser keeps the first value it sees for each key. Lines are processed in this order:

Priority Source
1 (highest) mergeWith
2 Override files / strings
3 (lowest) Base file / string

Note: mergeWith values cannot be overridden by the env file. If you want the .env file to take precedence over programmatic values, use override files instead of mergeWith.

State management
Member Description
dotenv.isInitialized true after load() or loadFromString() completes.
dotenv.clean() Clears all loaded variables and resets isInitialized to false.

After clean(), the instance is uninitialized. Accessing values will throw NotInitializedError until the next load() or loadFromString().

Errors
Error Thrown when
NotInitializedError Accessing values before calling load() or loadFromString().
FileNotFoundError The env file is not in the asset bundle (load() only).
EmptyEnvFileError The env file or string is empty.
AssertionError A required variable is missing and no fallback was provided.
FormatException A typed getter can't parse the value.

.env file syntax

# Comments start with #
KEY=value
QUOTED="double quoted value"
SINGLE='single quoted value'

# Variable interpolation
BASE_URL=https://api.example.com
FULL_URL=$BASE_URL/v1
ALT_URL=${BASE_URL}/v1

# Prevent interpolation with single quotes
PRICE='$9.99'

# Newlines in double quotes
MULTI="line1\nline2"

# The export keyword is stripped automatically
export EXPORTED=hello

Parsing rules:

  • Lines without = are ignored.
  • # starts a comment when it appears outside quoted values.
  • Double-quoted values unescape \" and expand \n to newlines, and interpolate $VAR / ${VAR}.
  • Single-quoted values do not interpolate variables. Escaped single quotes (\') are unescaped.
  • Use \$ for a literal dollar sign in unquoted or double-quoted values.
  • Undefined variables interpolate to an empty string.
  • Unquoted values are trimmed of surrounding whitespace.
  • If the same key appears multiple times anywhere in the processed input, the first occurrence wins (see value precedence).
  • Leading export keyword is stripped.
  • This is not a full shell parser. Complex shell expressions are not supported.

Multiple environments

Layer environment-specific values over a shared base using override files:

# .env
API_URL=https://api.example.com
LOG_LEVEL=warning
# .env.staging
API_URL=https://staging.api.example.com
LOG_LEVEL=debug
await dotenv.load(overrideWithFiles: ['.env.staging']);

dotenv.get('API_URL');   // => "https://staging.api.example.com"
dotenv.get('LOG_LEVEL'); // => "debug"

Override files take precedence over the base file. Register all env files as assets in pubspec.yaml.

Remote configuration

If you want to manage environment configs remotely and load them by config ID at runtime, see the companion package flutter_dotenv_remote. It also supports using the last successful config as a local fallback.

await dotenv.loadRemote(
  configId: 'your-config-id',
  useCacheOnFailure: true,
);

Multiple instances

The package exports a pre-created singleton dotenv for the common case. You can also create separate instances for different configurations — each instance maintains its own independent state:

final publicConfig = DotEnv();
final featureFlags = DotEnv();

await publicConfig.load(fileName: '.env');
await featureFlags.load(fileName: '.env.features');

String apiUrl = publicConfig.get('API_URL');
bool beta = featureFlags.getBool('BETA_ENABLED', fallback: false);

Merging with Platform.environment

On platforms where dart:io is available (mobile, desktop), you can merge system environment variables:

import 'dart:io' show Platform;

await dotenv.load(mergeWith: Platform.environment);

Merged values take precedence over values declared in the env file (see value precedence). Variables in the .env file can reference merged values:

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

Note: Platform.environment is not available on Flutter web.

Troubleshooting

Problem Cause Solution
FileNotFoundError The file isn't registered as an asset. Add the exact path to flutter: assets: in pubspec.yaml and restart the app.
EmptyEnvFileError The env file or string has no content. Add at least one KEY=value entry, or use isOptional: true.
NotInitializedError Accessing values before loading. Call await dotenv.load() in main() before runApp().
NotInitializedError despite load() in main() Values read in top-level initializers run before main(). Move reads inside functions, widgets, or callbacks.
dotenv.env['NAME'] returns null Key mismatch or the file wasn't loaded. Check for typos. Verify load() completed successfully.
mergeWith value not overridden by .env mergeWith has highest precedence. Move the value into an override file, or stop passing it via mergeWith.
Web deploy: file not found Web servers may ignore dotfiles. Rename the file (e.g. env or config.env) and update fileName and pubspec.yaml.
FormatException on typed getter The value can't be parsed as the requested type. Check the raw value with dotenv.env['NAME'].

Migration from older versions

v5.x to v6.0:

  • testLoad() was renamed to loadFromString().
  • Empty files with isOptional: true no longer throw.

v4.x to v5.0:

  • Methods moved from top-level functions into the DotEnv class.
  • Replace load() with dotenv.load() and env['X'] with dotenv.env['X'].

Example

See the example app for a complete working project, or browse the API docs on pub.dev.

Contributing

Issue tracker — bug reports and feature requests welcome. Pull requests are welcome.

Support

Sponsor on GitHub

"Buy Me A Coffee"

License

MIT

所属分类

源码仓库

使用此插件的项目

所在榜单