배포와 운영 기초집LESSON 11

환경 변수와 .env 파일: 설정과 비밀 정보 분리

난이도입문 → 초급

예상 시간30분

선수지식이전 강의

11강. 환경 변수와 .env 파일: 설정과 비밀 정보 분리

1. 이번 강의에서 해결할 문제

API 주소와 토큰을 소스에 직접 쓰면 환경 변경이 어렵고 정적 번들·Git 이력에 비밀이 남습니다. 공개 가능한 설정과 비밀을 구분합니다.

2. 학습 목표

3. 핵심 개념

환경 변수는 실행 환경이 코드에 설정을 전달하는 통로입니다. .env는 편리한 로컬 파일일 뿐 자동 암호화되지 않으며 Git에서 제외해야 합니다. Docusaurus나 Vite 빌드가 브라우저 코드에 포함한 값은 사용자가 내려받아 볼 수 있으므로 API Key·토큰·비밀번호를 넣을 수 없습니다. 서버 비밀은 서버 런타임에서만 읽어야 합니다.

4. 단계별 실습

1. PowerShell

실행 위치: 저장소 루트

실행 전 확인: 실제 토큰이나 운영 주소를 명령 기록에 넣지 않습니다.

대상: 현재 터미널 세션의 공개 설정 예시

PowerShell
$env:SITE_ENV = "local"
$env:PUBLIC_DOCS_URL = "http://localhost:3000"
Get-ChildItem Env:SITE_ENV, Env:PUBLIC_DOCS_URL

예상 결과: 현재 PowerShell 프로세스와 자식 프로세스에서 읽을 두 공개 설정이 표시됩니다.

2. 파일 편집

실행 위치: 저장소 루트

실행 전 확인: 기존 .gitignore 내용을 덮지 말고 필요한 줄의 존재를 먼저 검색합니다.

대상: .env.example과 .gitignore 예시

.env.example
SITE_ENV=local
PUBLIC_DOCS_URL=http://localhost:3000
API_TOKEN=

.gitignore에 추가할 예시
.env
.env.*
!.env.example
*.pem
*.key

예상 결과: 공유 템플릿에는 변수 이름과 가상 공개 값만 있고 비밀 값은 비어 있으며, 로컬 비밀 파일과 개인 키는 Git 추적 대상에서 제외됩니다.

3. PowerShell

실행 위치: 저장소 루트

실행 전 확인: 검색 결과를 화면 공유하기 전 실제 비밀이 출력되지 않게 주의합니다.

대상: Git 추적·비밀 패턴 점검

PowerShell
git check-ignore -v .env
git ls-files .env .env.local
git grep -n -I -E "API_TOKEN=.+|BEGIN .*PRIVATE KEY"

예상 결과: .env가 ignore되고 추적 파일에는 비밀 패턴이 없어야 합니다.

5. 배포·운영 흐름이 동작하는 이유

프로세스 환경은 실행 시점 설정을 제공하고 예제 파일은 필요한 변수 이름을 문서화합니다. Git ignore와 추적 파일 검색이 로컬 비밀이 배포 입력에 들어가지 않도록 이중 확인합니다.

6. 자주 하는 실수와 안전한 해결법

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ