환경변수의 필요성
환경변수(Environment Variaable)란 애플리케이션 실행 환경에 따라 달라질 수 있는 설정 값 을 의미한다.😊
☝️ 보안성 강화
소스코드에 민감한 정보를 하드코딩해 사용하게 되면
무단 액세스 또는 데이터 유출과 같은 보안 위험이 발생할 수 있다.👿
Ex ) 외부 서비스 API Key, Secret Key, Token 등 ...
✌️ 환경 분리
개발(Development), 스테이징(Staging), 운영(Production) 등
각 환경에 맞는 설정을 하는데 사용한다.
Ex) API 엔드포인트, 데이터베이스 URL, 스토리지 URL 등 ...
👌 유지보수성 향상
특정 값을 코드에 하드코딩하지 않고 변수로 관리하여
애플리케이션 자체를 수정하지 않고도 동작을 변경할 수 있게 한다.
Ex) 외부 서비스 API 주소, Base URL, 로그 레벨 등 ...
🚨 주의사항
클라이언트로 전달되는 환경변수는 반드시 공개되어도
괜찮은 값만 사용해야 한다.
환경변수 설정 방법 📝
1. process.env.NODE_ENV 변수
Next.js가 구동 환경에 따라 자동으로 생성해주는 환경변수이다.
서버와 클라이언트에서 모두 참조할 수 있다.😁
- development: 개발환경 ( npm run dev로 실행한 경우 )
- production: 배포환경 ( npm run build, next start 로 실행한 경우)
- test: 테스트 환경 (Jest or Vitest 를 실행 한 경우)
// next.config.ts
console.log("$$$$ NODE_ENV: ", process.env.NODE_ENV);
// npm run dev
$$$$ NODE_ENV: development
// npm run build
$$$$ NODE_ENV: production
2. env 파일의 종류와 우선순위🏆
구동 환경별 환경 변수를 정의하는 파일이다.
해당 파일에 정의한 환경변수는 process.env.변수명 으로 로드할 수 있다.
- .env: 모든 환경에서 공통으로 적용할 default 환경 변수를 정의한다.
- .env.development: 개발 환경에서 적용
- .env.production: 배포 / 빌드 환경에서 적용
- .env.local 가장 우선순위가 높아 다른 파일에 영향을 받지 않음
우선순위는
.env.local > .env.${mode} > .env 순으로 높다
.env.local 파일의 우선순위가 가장 높은 이유 💡
개발에 필요한 개인의 로컬 환경변수로 사용되며
팀 공통 설정을 로컬에서 안전하게 덮어쓸 때 사용한다.
그래서.env.local은 기본적으로 .gitignore에 포함된다.
//.env
# 모든 환경에서 기본으로 사용하는 값
NEXT_PUBLIC_API_URL=https://api.env.com
NEXT_PUBLIC_APP_NAME=next-env-example
//.env.development
# 개발 환경에서만 덮어쓰는 값
NEXT_PUBLIC_API_URL=https://api.env.development.com
//.env.local
NEXT_PUBLIC_API_URL=https://api.env.local.com
// src/app/page.tsx
export default function Page() {
console.log('$$$$ API URL:', process.env.NEXT_PUBLIC_API_URL);
console.log('$$$$ APP NAME:', process.env.NEXT_PUBLIC_APP_NAME);
return <div>Check console</div>;
}
// npm run dev
$$$$ API URL: https://api.env.local.com
$$$$ APP NAME: next-env-example
3. NEXT_PUBLIC_ 접두사의 의미
Next.js에서는 기본적으로 서버에서만 환경변수를 참조할 수 있다.
서버와 클라이언트 모두에서 환경변수를 참조하려면 변수명 앞에 NEXT_PUBLIC 를 붙여주어야 한다.😯
4. next.config 의 env 옵션
next.config.js의 env 옵션에 선언한 값도 process.env로 접근할 수 있다.
...
const nextConfig = {
env: {
VERSION: "1.2.1.5",
BUILD_TIME: new Date().toISOString(),
},
};
export default nextConfig;다만, 이 방식은 모든 값이 클라이언트 번들에 포함되며,
NEXT_PUBLIC_ 접두사와 상관없이 노출된다. 🚨
따라서 보안이 필요한 환경변수 관리 용도로는 적합하지 않으며,
빌드 설정과 관련된 상수 값을 전달할 때만 제한적으로 사용하는 것이 좋다.👍
마무리
환경변수는 단순한 설정 값처럼 보이지만,
보안, 배포, 유지보수와 깊게 연결된 중요한 요소다.
Next.js의 환경변수 규칙을 정확히 이해하고 사용한다면
보다 안전하고 확장성 있는 프로젝트를 만들 수 있다.
