meepin env
env guide
dev, stage, prod 환경을 분리하여 구성하는 방법과, 이를 위해 사용하는 dotenv와 cross-env의 역할 및 설정 방법을 자세히 설명합니다.
⸻
- 필요한 패키지 설치
환경 변수 파일을 로드하기 위해 dotenv를, 그리고 OS에 관계없이 환경 변수를 설정하기 위해 cross-env를 설치합니다.
npm install dotenv npm install --save-dev cross-env
• dotenv: 지정한 .env 파일의 내용을 읽어 process.env에 주입하여 애플리케이션 전역에서 환경 변수에 접근할 수 있게 합니다.
• cross-env: Windows, macOS, Linux 등 어떤 운영체제에서도 동일한 방식으로 환경 변수를 설정할 수 있도록 도와줍니다.
⸻
- 환경 변수 파일 구성 (env 폴더 사용)
프로젝트 루트에 env 폴더를 생성하고, 그 안에 아래와 같이 세 개의 환경 파일을 만듭니다.
3.1. env/env.dev
개발 환경에 사용될 변수들을 정의합니다.
envs/env.dev
NEXT_PUBLIC_API_URL=http://localhost:3000/api
3.2. envs/env.stage
스테이징(검증) 환경에 사용될 변수들을 정의합니다.
envs/env.stage
NEXT_PUBLIC_API_URL=https://stage.example.com/api
3.3. envs/env.prod
운영(프로덕션) 환경에 사용될 변수들을 정의합니다.
envs/env.prod
NEXT_PUBLIC_API_URL=https://example.com/api
각 파일에는 해당 환경에서 사용할 API URL 또는 기타 설정 값을 작성합니다.
⸻
- next.config.js 설정
Next.js는 기본적으로 .env 파일들을 자동으로 로드하지 않으므로, dotenv를 사용해 환경 파일을 명시적으로 로드해야 합니다. 아래 예제에서는 APP_ENV 환경 변수 값에 따라 env 폴더 내부의 환경 파일을 로드하도록 설정합니다.
// next.config.js const fs = require('fs'); const path = require('path'); const dotenv = require('dotenv');
// APP_ENV 환경 변수를 사용하여 어떤 env 파일을 로드할지 결정 (기본값: 'dev')
const appEnv = process.env.APP_ENV || 'dev';
// env 폴더 내부의 환경 파일을 로드합니다.
const envPath = path.resolve(__dirname, env/env.${appEnv});
if (fs.existsSync(envPath)) {
console.log(Loading environment variables from: ${envPath});
dotenv.config({ path: envPath });
} else {
console.warn(Environment file not found: ${envPath});
}
const nextConfig = { // Next.js Standalone Output 설정 (필요한 경우) output: "standalone", // env 객체를 통해 클라이언트에서 사용 가능한 환경 변수를 지정합니다. env: { NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL, // 추가적으로 필요한 환경 변수들을 여기에 넣으세요. }, };
module.exports = nextConfig;
코드 설명 • fs와 path 모듈을 사용해 환경 파일의 존재 여부를 확인합니다. • process.env.APP_ENV 변수 값(예: dev, stage, prod)에 따라 env/env.dev, env/env.stage, env/env.prod 중 하나를 로드합니다. 기본값은 dev입니다. • dotenv.config({ path: envPath })를 사용해 지정한 파일에 작성된 변수들을 process.env에 주입합니다. • Next.js 설정의 env 옵션에 NEXT_PUBLIC_API_URL을 지정하여 클라이언트에서도 해당 변수에 접근할 수 있도록 합니다.
⸻
- package.json 스크립트 설정
각 환경에 맞게 빌드 및 실행할 수 있도록 cross-env를 활용해 npm 스크립트를 작성합니다.
package.json 파일의 "scripts" 섹션을 아래와 같이 수정하세요.
{ "name": "my-next-project", "version": "0.1.0", "private": true, "scripts": { "dev": "cross-env APP_ENV=dev next dev --turbopack", "build:dev": "cross-env APP_ENV=dev next build", "build:stage": "cross-env APP_ENV=stage next build", "build:prod": "cross-env APP_ENV=prod next build", "start:dev": "cross-env APP_ENV=dev next start", "start:stage": "cross-env APP_ENV=stage next start", "start:prod": "cross-env APP_ENV=prod next start", "lint": "next lint" }, "dependencies": { // ... 기타 의존성들 }, "devDependencies": { "cross-env": "^7.0.3", "dotenv": "^16.0.0" // ... 기타 dev 의존성들 } }
스크립트 설명 • dev: 개발 환경에서 Next.js 개발 서버를 실행하며, APP_ENV=dev를 설정하여 env/env.dev 파일을 로드합니다. • build:dev, build:stage, build:prod: 각각의 환경에 대해 빌드 시 APP_ENV 값을 설정해 올바른 환경 파일이 로드되도록 합니다. • start:dev, start:stage, start:prod: 빌드 후 서버 실행 시에도 동일하게 환경 변수를 설정합니다.
⸻
- 사용 예시
예를 들어, 스테이징 환경에서 애플리케이션을 빌드하고 실행하려면 아래 명령어를 사용합니다.
npm run build:stage npm run start:stage
이렇게 하면 APP_ENV가 stage로 설정되어 env/env.stage 파일의 환경 변수들이 로드되고, 스테이징 환경에 맞는 설정으로 애플리케이션이 동작하게 됩니다.
⸻
- 결론
위와 같이 구성하면 Next.js 프로젝트에서 다음과 같은 이점을 누릴 수 있습니다. • 환경별 설정 관리: 환경 변수 파일을 루트의 env 폴더 내에 분리하여 관리하므로, 환경 간 설정 충돌을 방지하고 유지보수가 용이해집니다. • dotenv의 역할: dotenv는 지정한 환경 파일의 내용을 process.env에 주입해 애플리케이션 전역에서 환경 변수에 접근할 수 있도록 합니다. • cross-env의 역할: cross-env를 통해 운영체제에 관계없이 npm 스크립트에서 환경 변수를 동일한 방식으로 설정할 수 있습니다. • 유연한 빌드 및 실행: 각 환경에 맞게 빌드 및 실행 스크립트를 작성하여 원하는 환경 설정으로 애플리케이션을 구동할 수 있습니다.
이 가이드를 내부 문서나 위키에 남겨두면, 프로젝트 팀원들이 환경 설정 방법을 쉽게 이해하고 관리할 수 있을 것입니다.
⸻