환경변수 .env 파일 차이: local, example, development 기준

환경 변수는 왜 사용하는가

코드 안에 환경별 값을 직접 작성하면 개발, 테스트, 배포 환경을 바꿀 때 소스 코드를 수정해야 합니다.

const apiUrl = 'http://localhost:3000';

환경 변수로 분리하면 실행 환경에 따라 값을 바꿀 수 있습니다.

const apiUrl = import.meta.env.VITE_API_URL;

하지만 환경 변수 파일은 비밀 저장소가 아닙니다. 특히 브라우저 번들에 포함되는 변수는 사용자가 확인할 수 있습니다.

파일 역할 먼저 구분하기

프로젝트마다 도구의 로딩 규칙은 다를 수 있지만, Vite를 사용하는 TaskFlow에서는 다음 기준으로 이해합니다.

.env
→ 모든 mode에서 사용할 공통 기본값

.env.local
→ 현재 PC에서만 사용할 로컬 덮어쓰기 값

.env.development
→ development mode 전용 값

.env.production
→ production mode 전용 값

.env.example
→ 저장소에 공유할 변수 이름과 예시 형식

.local 계열 파일은 개인 환경 값을 담는 용도로 사용하고 일반적으로 Git에서 제외합니다.

.env.example은 왜 필요한가

.env 파일을 모두 .gitignore에 넣기만 하면 새 개발자는 어떤 변수가 필요한지 알 수 없습니다.

그래서 실제 값이 없는 .env.example을 함께 관리합니다.

VITE_API_URL=https://example.invalid
VITE_APP_NAME=TaskFlow

새 환경에서는 이 파일을 보고 필요한 변수를 준비합니다.

.env.example
→ 어떤 변수 이름이 필요한지 공개

.env.local
→ 내 PC의 실제 값

실제 비밀 값은 넣지 않기

다음 값은 예시 문서나 공개 저장소에 넣지 않습니다.

비밀번호
개인 액세스 토큰
서버 전용 secret
service account private key
실제 API secret

또한 브라우저에서 읽는 환경 변수는 변수 이름에 secret이 들어간다고 해서 비밀이 되지 않습니다.

클라이언트 번들에 들어가는 값은 사용자가 볼 수 있다고 가정해야 합니다.

값은 문자열로 읽힌다

환경 변수에 숫자나 boolean처럼 보이는 값을 넣어도 클라이언트에서 문자열로 다뤄질 수 있습니다.

VITE_PAGE_SIZE=20
VITE_FEATURE_ENABLED=true

코드에서 필요한 타입으로 변환합니다.

const pageSize = Number(import.meta.env.VITE_PAGE_SIZE);
const featureEnabled =
  import.meta.env.VITE_FEATURE_ENABLED === 'true';

변환에 실패했을 때의 처리도 필요합니다.

const rawPageSize = Number(import.meta.env.VITE_PAGE_SIZE);
const pageSize = Number.isFinite(rawPageSize)
  ? rawPageSize
  : 20;

환경 변수가 안 읽힐 때 확인 순서

1. 파일 이름 확인
2. 프로젝트 루트 위치 확인
3. 현재 mode 확인
4. 변수 prefix 확인
5. 개발 서버 재시작
6. 실제 코드 참조 위치 확인

무조건 .env 파일을 여러 개 복사하거나 변수 이름을 바꾸는 방식으로 해결하지 않습니다.

.env 파일을 수정했는데 화면이 안 바뀝니다

환경 변수는 개발 서버가 시작될 때 읽히는 경우가 많습니다.

서버를 재시작해 확인합니다.

Ctrl + C
pnpm dev

process.env를 쓰면 되나요

Vite 클라이언트 코드에서는 기본적으로 import.meta.env를 기준으로 사용합니다.

import.meta.env.VITE_API_URL

Node.js 서버 코드나 다른 프레임워크는 별도 규칙을 사용할 수 있습니다. 환경 변수 접근 문법을 프로젝트 도구와 섞지 않는 것이 중요합니다.

학습 완료 체크리스트

• .env와 .env.local의 역할을 구분할 수 있습니다.
• .env.development 같은 mode별 파일을 이해했습니다.
• .env.example에 실제 비밀 값을 넣지 않습니다.
• 브라우저 환경 변수는 비밀 저장소가 아니라는 점을 이해했습니다.
• 환경 변수 값이 문자열로 읽힐 수 있음을 알고 있습니다.
• 환경 변수 로딩 문제를 파일 이름부터 순서대로 확인할 수 있습니다.

pnpm dev

VITE_API_URL=https://api.example.invalid
VITE_APP_NAME=TaskFlow

VITE_API_URL=http://localhost:4000
VITE_APP_NAME=TaskFlow Local

.env.local
.env.*.local

pnpm dev
pnpm build

pnpm --filter @taskflow/web exec vite --mode staging

dev-env-step-02-package-manager-choice

.env.example 추가
.env.local Git 제외 기준 정리
VITE_API_URL 정의
VITE_APP_NAME 정의
환경 변수 문서화

.env.example
.gitignore
docs/development-environment.md

VITE_API_URL=https://api.example.invalid
VITE_APP_NAME=TaskFlow

pnpm dev

dev-env-step-03-env-contract

node_modules/
dist/
storybook-static/
.env.local
.env.*.local

VITE_API_URL=https://api.example.invalid
VITE_APP_NAME=TaskFlow

<!doctype html>
<html lang="ko">
<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>TaskFlow 개발환경</title></head>
<body><main id="app"></main><script type="module" src="/src/main.js"></script></body>
</html>

{
  "name": "@taskflow/web",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "vite build"
  },
  "devDependencies": {
    "vite": "8.3.0"
  }
}

import './style.css';

const app = document.querySelector('#app');
const title = document.createElement('h1');
title.textContent = 'TaskFlow';
const status = document.createElement('p');
status.textContent = '개발환경 스타터가 실행 중입니다.';
app.append(title, status);

body { margin: 0; color: #202020; background: #f6f6f6; font: 16px/1.6 system-ui, sans-serif; }
main { max-width: 720px; margin: 64px auto; padding: 24px; }
h1 { font-size: 30px; font-weight: 500; }
p { overflow-wrap: anywhere; }

# TaskFlow 개발환경

이 스타터는 개발환경 진단을 위한 최소 Vite/vanilla JavaScript 앱입니다. 할 일 관리 기능이나 API 서버는 포함하지 않습니다.

Node.js 24.19.0, pnpm 11.19.0으로 검증했습니다. 루트는 pnpm만 사용하며 apps/*만 workspace입니다. labs의 npm/Yarn/pnpm 실습은 독립 프로젝트입니다.

## 2회차

메인 앱은 pnpm을 유지합니다. labs/yarn-modern은 독립 Yarn 실습입니다.

## 3회차

apps/web/.env.example을 apps/web/.env.local로 복사합니다. .invalid 주소는 표시만 하며 실제 API 호출은 하지 않습니다. 공개 샘플값만 제공하고 로컬 파일은 ZIP에서 제외합니다.

{
  "name": "taskflow",
  "private": true,
  "packageManager": "pnpm@11.19.0",
  "engines": {
    "node": ">=24"
  },
  "scripts": {
    "dev": "pnpm --filter @taskflow/web dev",
    "build": "pnpm --filter @taskflow/web build"
  }
}

packages:
  - "apps/*"

# TaskFlow 개발환경 03 완료 체크포인트

Node.js 24.19.0 / pnpm 11.19.0 검증 기준입니다. pnpm을 별도로 설치한 환경에서 실행하세요. ZIP에는 node_modules, dist, 로컬 환경 변수, 실제 비밀값이 없습니다.

1. 이 폴더에서 `pnpm install --frozen-lockfile`
2. PowerShell: `Copy-Item apps/web/.env.example apps/web/.env.local` 또는 macOS/Linux: `cp apps/web/.env.example apps/web/.env.local`
3. `pnpm dev` 후 http://127.0.0.1:5173 확인
4. `pnpm build`

ESLint는 5회차부터 추가되므로 이 체크포인트에는 lint 명령이 없습니다.

apps/web가 Vite 루트입니다. 환경 변수도 이 폴더에 둡니다. 표시용 API 주소에 실제 요청을 보내지 않습니다. labs는 메인 workspace에서 제외되어 각 폴더에서 별도 설치합니다.

원문 단계별 전체 파일과 실행 검증 범위는 docs/development-environment.md를 확인하세요.

nodeLinker: node-modules

{
  "name": "taskflow-yarn-lab",
  "private": true,
  "type": "module",
  "packageManager": "yarn@4.18.0",
  "scripts": {
    "dev": "node src/main.js",
    "lint": "node --check src/main.js"
  }
}

console.log('TaskFlow Yarn 독립 실습');

다음 학습

다음 글에서는 환경 변수 파일은 정상인데 import.meta.env 값이 undefined로 나오는 문제를 재현합니다.

다음 글: Vite import.meta.env undefined 해결: VITE_ prefix 기준

공식 문서

• Vite Env Variables and Modes: https://vite.dev/guide/env-and-mode
• Vite Shared Options envPrefix: https://vite.dev/config/shared-options