.env

기본 정보

• 명칭: .env
• 영문명: Environment File
• 분류: 환경 변수(Environment Variables)
• 파일명: .env
• 주요 용도: 애플리케이션 설정 및 민감한 정보 관리
• 관련 기술: 환경 변수, Docker, Git, PHP, Node.js

개요

.env 파일은 애플리케이션의 환경 설정(Environment Variables)을 저장하는 파일이다.

데이터베이스 정보, API Key, JWT Secret, SMTP 계정, 외부 서비스 URL 등 소스 코드에 직접 작성하면 안 되는 설정값을 분리하여 관리하는 것이 목적이다.

이를 통해 개발(Development), 테스트(Test), 운영(Production) 환경에서 서로 다른 설정을 사용할 수 있으며, 보안성과 유지보수성이 크게 향상된다.

.env 구조

Application

↓

.env

↓

Environment Variables

↓

Application Config

동작 과정

프로그램 실행

↓

.env 읽기

↓

환경 변수 등록

↓

설정값 사용

↓

애플리케이션 실행

기본 문법

APP_NAME=MyApp
APP_ENV=production
APP_DEBUG=false

DB_HOST=localhost
DB_PORT=3306
DB_NAME=my_database
DB_USER=root
DB_PASSWORD=password

규칙

• KEY=VALUE 형태 사용
• 공백 없이 작성
• 주석은 # 사용
• 문자열은 일반적으로 따옴표 없이 작성 가능

주석 작성

# 데이터베이스 설정
DB_HOST=localhost

문자열

APP_NAME="My Application"

공백이 포함될 경우 큰따옴표를 사용하는 것이 좋다.

Boolean 값

APP_DEBUG=true
APP_CACHE=false

대표 설정 예시

APP_NAME=MyApp
APP_ENV=production

DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=mydb
DB_USERNAME=root
DB_PASSWORD=1234

REDIS_HOST=127.0.0.1

JWT_SECRET=my-secret-key

OPENAI_API_KEY=xxxxxxxx

PHP 사용 예시

$dbHost = $_ENV['DB_HOST'];
$dbUser = $_ENV['DB_USERNAME'];
$dbPass = $_ENV['DB_PASSWORD'];

일반적으로 vlucas/phpdotenv 라이브러리를 사용하여 .env 파일을 로드한다.

Node.js 사용 예시

먼저 라이브러리를 설치한다.

npm install dotenv

사용 예시

require("dotenv").config();

console.log(process.env.DB_HOST);

Python 사용 예시

설치

pip install python-dotenv

사용

from dotenv import load_dotenv
import os

load_dotenv()

db_host = os.getenv("DB_HOST")

Docker에서 사용

Docker Compose에서도 .env 파일을 사용할 수 있다.

services:
  app:
    image: myapp
    env_file:
      - .env

Docker Compose 변수 사용

version: "3"

services:
  mysql:
    image: mysql:8

    environment:
      MYSQL_DATABASE: ${DB_DATABASE}
      MYSQL_USER: ${DB_USERNAME}
      MYSQL_PASSWORD: ${DB_PASSWORD}

Git과 .env

.env 파일은 일반적으로 Git에 포함하지 않는다.

.gitignore

.env
.env.local
.env.production

.env.example

실무에서는 .env.example 파일을 함께 제공한다.

APP_NAME=

DB_HOST=

DB_PORT=

DB_DATABASE=

DB_USERNAME=

DB_PASSWORD=

실제 비밀번호는 포함하지 않는다.

환경별 관리

대표적인 구성

.env

.env.local

.env.development

.env.staging

.env.production

자주 사용하는 환경 변수

.env와 환경 변수 비교

장점

• 민감한 정보 분리
• 환경별 설정 가능
• 유지보수 용이
• 보안 향상
• 설정 변경이 쉬움
• 코드 수정 없이 환경 변경 가능

단점

• 잘못 관리하면 정보 유출 가능
• 운영 서버에서는 별도 관리가 필요
• 환경 변수 누락 시 오류 발생 가능

대표 활용 분야

• 웹 애플리케이션
• REST API
• Docker 프로젝트
• AI 서비스
• SaaS
• CI/CD
• Node.js 서버
• PHP 프로젝트

실무 메모

실무에서는 다음과 같은 방식이 권장된다.

• .env는 Git에 업로드하지 않기
• .env.example 함께 제공
• 운영 서버는 OS 환경 변수 사용 고려
• API Key는 주기적으로 교체
• Secret 값은 암호화 저장 검토
• 환경별 .env 분리
• 민감한 정보 로그 출력 금지
• 설정값 검증 로직 추가
• CI/CD Secret과 연동
• 접근 권한 최소화

.env와 함께 사용하는 기술

• 환경 변수
• Docker
• Docker Compose
• Git
• PHP
• Node.js
• Python
• CI/CD
• AWS
• GitHub Actions

대표 활용 사례

• Laravel 프로젝트
• Express 서버
• Django 프로젝트
• Docker Compose
• AI API 설정
• MySQL 연결
• SMTP 메일 서버
• Redis 연결

관련 문서

• 환경 변수
• Docker
• Docker Compose
• Git
• PHP
• Node.js
• Python
• CI/CD
• AWS
• GitHub Actions

출처

• The Twelve-Factor App
• dotenv 공식 프로젝트
• Docker 공식 문서