Next.js 공식 문서를 읽고, 필자가 생각하기에 Next.js에 대해 알고 있어야 하는 핵심 개념을 정리한 포스팅입니다. 실제로 Next.js 공식 문서를 살펴보면 생각보다 많은 내용이 있는데, 필자의 목적은 "Next.js가 무엇이냐"라는 질문에 대해 답을 할 수 있는 수준의 핵심 개념을 간추리는 것입니다. 더 자세한 내용은 개발하면서 그때그때 살펴보면 된다고 생각합니다.
Next.js는 다음과 같은 환경 변수 파일들을 통해 자체적으로 환경 변수를 지원한다.
환경 | Default 환경 변수(원격 저장소 푸시 O) | Secret 환경 변수(원격 저장소 푸시 X) |
모든 환경 | .env | .env.local |
개발 환경 ( next dev ) | .env.development | .env.development.local |
배포 환경 ( next start ) | .env.production | .env.production.local |
테스트 환경 ( jest , cypress 등) | .env.test | .env.test.local |
환경 변수 파일들의 적용 우선순위는 다음과 같이 결정된다.
- (환경에 따라)
.env.development.local
,.env.production.local
,.env.test.local
- (테스트 환경이 아닌 경우)
.env.local
- (환경에 따라)
.env.development
,.env.production
,.env.test
- (모든 환경)
.env
1. 환경 변수 로드하기
Next.js는 프로젝트 폴더에 존재하는 환경 변수 파일(
.env*
)로부터 환경 변수를 읽어 Node.js 환경의 process.env
객체에 주입한다. 따라서 getStaticProps()
함수와 같은 곳에서도 환경 변수를 자유롭게 읽고 사용할 수 있다. 다음은 예시 코드이다.서버에서만 사용하는 비밀 값들을 안전하게 보관하기 위해, Next.js는
process.env.*
형식의 값을 전부 빌드 타임에 올바른 값으로 치환한다. 이는 process.env
객체를 일반적인 JavaScript 객체처럼 다룰 수 없음을 의미하며, 따라서 이 객체를 대상으로 구조 분해 할당(Object Destructing)과 같은 문법을 사용할 수 없다. 따라서 const { PUBLISHABLE_KEY } = process.env
와 같은 코드는 사용할 수 없고, 반드시 process.env.PUBLISHABLE_KEY
의 형식으로 코드를 작성해야 한다.환경 변수 파일(
.env*
) 내에서 $VAR
문법을 사용하여 또 다른 환경 변수를 참조하는 것도 가능하다. 그리고 $
문자 자체를 값으로 사용하고 싶을 때는 \$
로 이스케이프하면 된다.2. 브라우저에 환경 변수 노출하기
기본적으로 환경 변수 파일로부터 로드한 환경 변수들은 Node.js 환경에서만 접근이 가능하고 브라우저에서는 접근이 불가하다. 만약 브라우저에서도 접근하고 싶은 환경 변수가 있다면, 그 환경 변수의 이름을
NEXT_PUBLIC_XXX
형식으로 지정하면 된다.그러면 그 환경 변수는 빌드 타임에 브라우저에게 전달되는 JavaScript에 인라인으로 삽입되어 브라우저에서 동작하는 코드에서도
process.env.*
형식의 코드로 해당 환경 변수에 접근할 수 있게 된다.3. Vercel에서 환경 변수 설정하기
Next.js 앱을 Vercel로 배포하는 경우, 개발 환경을 포함한 모든 환경의 환경 변수들은 프로젝트 설정에서 해줘야 한다. 이 환경 변수들은 원한다면
vercel env pull .env.local
명령어를 실행함으로써 로컬에 다운로드하여 로컬 개발 환경 구축에 활용할 수 있다.만약 Vercel CLI를 이용하여 배포를 진행한다면, 반드시
.gitignore
파일과 동일한 내용을 담은 .vercelignore
파일을 만들어 줘야 한다는 것에 주의하도록 하자.4. 테스트 환경
테스트 환경이란,
jest
, cypress
와 같은 테스트 툴에 의해 테스트를 하는 환경을 일컫는다. 테스트 환경을 위한 환경 변수들의 Default 값은 .env.test
파일에, Secret 값은 .env.test.local
파일에 작성하면 된다.이 파일들과 다른 환경 변수 파일들의 가장 큰 차이는
.env.local
파일을 무시한다는 점이다. 그래야 어떠한 환경에서도 동일한 환경 변수들의 집합을 가지고 똑같은 테스트를 수행할 수 있기 때문이다.이러한 환경 변수들이 로드되려면
NODE_ENV
의 값이 test
로 설정되어 있어야 하는데, 대부분의 테스트 툴들은 이를 알아서 처리해주기 때문에 개발자가 별도로 신경 써줄 부분은 없다.