패키지, 저장소 및 앱 카테고리 검색

패키지 상세v6.0.2

flutter_dotenv

.env 파일을 사용하여 어떤 플러터 애플리케이션도 전역 변수로 쉽게 구성할 수 있습니다.

AndroidiOSWebmacOSWindowsLinux
30일 다운로드
101만
좋아요
2.3천
Pub 점수
160

패키지 설치

flutter pub add flutter_dotenv

패키지 개요

공개 정보를 바탕으로 생성한 선택 가이드입니다.

flutter_dotenv는 개발자가 .env 파일을 사용하여 애플리케이션 내의 환경 변수를 관리할 수 있도록 해주는 Flutter 패키지입니다. 실행 시 파일에서 키-값 쌍을 로드함으로써 구성 작업을 간소화하여 개발, 테스트 및 프로덕션 환경 간의 다양한 설정을 쉽게 처리할 수 있습니다. 이 패키지는 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

카테고리

소스 저장소

이 패키지를 사용하는 프로젝트

순위