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
Load configuration into your Flutter app from a .env asset file or string.
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 initializerfinal 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.
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).
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 automaticallyexport 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:
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.
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: