[Next.js] 핵심 개념 익히기 - ⑤ 환경 변수 사용하기

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

환경 변수 파일들의 적용 우선순위는 다음과 같이 결정된다.

1. (환경에 따라) .env.development.local, .env.production.local, .env.test.local
2. (테스트 환경이 아닌 경우) .env.local
3. (환경에 따라) .env.development, .env.production, .env.test
4. (모든 환경) .env

 

1. 환경 변수 로드하기

Next.js는 프로젝트 폴더에 존재하는 환경 변수 파일(.env*)로부터 환경 변수를 읽어 Node.js 환경의 process.env 객체에 주입한다. 따라서 getStaticProps() 함수와 같은 곳에서도 환경 변수를 자유롭게 읽고 사용할 수 있다. 다음은 예시 코드이다.

// .env.local

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

// pages/index.js

export async function getStaticProps() {
    const db = await myDB.connect({
        host: process.env.DB_HOST,
        username: process.env.DB_USER,
        password: process.env.DB_PASS
    });
    // ...
}

서버에서만 사용하는 비밀 값들을 안전하게 보관하기 위해, 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 형식으로 지정하면 된다.

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

그러면 그 환경 변수는 빌드 타임에 브라우저에게 전달되는 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로 설정되어 있어야 하는데, 대부분의 테스트 툴들은 이를 알아서 처리해주기 때문에 개발자가 별도로 신경 써줄 부분은 없다.