처음 만난 Next.js 문서
13.2
환경 변수 설정
Next.js에서는 환경 변수를 설정할 수 있는 기능을 자체적으로 제공합니다. 그래서 별도의 추가설정 없이도 아래와 같은 방법을 이용하여 편리하게 환경 변수를 설정할 수 있습니다.
13.2.1 .env 파일을 이용한 환경 변수 설정
먼저 Next.js 프로젝트의 최상위 경로에 환경 변수 파일(예: .env.local)을 생성하고, 아래와 같은 형태의 키-값 쌍(Key-Value pair)을 작성하면 됩니다.
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=12345678
그러면 애플리케이션 내에서 아래 예시 코드와 같이 process.env.<키 값> 형태로 환경 변수의 값을 가져와서 사용할 수 있습니다.
// app/api/posts/route.ts
export async function GET() {
const connection = await db.connect({
host: process.env.DB_HOST,
port: process.env.DB_PORT,
username: process.env.DB_USER,
password: process.env.DB_PASSWORD,
});
}
참고로 아래와 같이 여러 줄에 걸친 값도 줄바꿈이나 개행문자(\n)를 사용해서 환경 변수로 설정해서 사용할 수 있으며, $를 사용하여 다른 환경 변수의 값을 참조하는 형태로도 값을 작성할 수 있습니다.
MY_VARIABLE_1="this
is
multiline
variable"
MY_VARIABLE_2="this\nis\nmultiline\nvariable"
USER_ID=soaple
USER_URL=https://example.com/$USER_ID
Next.js에서 환경 변수 파일을 불러오는 순서는 아래와 같습니다. 이 순서를 따라서 값을 탐색하게 되며, 가장 먼저 발견되는 환경 변수의 값이 사용됩니다.
process.env.env.$(NODE_ENV).local.env.local(NODE_ENV의 값이test일 경우 체크하지 않음).env.$(NODE_ENV).env
예를 들어, NODE_ENV의 값이 development이고 .env.development.local과 .env파일에 모두 환경 변수 값을 설정한 경우, .env.development.local에 설정된 값이 사용된다고 이해하면 됩니다.
13.2.2 브라우저에서 접근 가능한 환경 변수 설정
일반적으로 환경 변수는 Node.js 환경에서만 접근 가능합니다. 즉, 백엔드 환경에서만 접근 가능하며, 프론트엔드 환경(브라우저)에서는 접근이 불가능 합니다. 만약 프론트엔드에서 접근해야 할 필요가 있을 경우 아래와 같이 환경 변수의 키 값을 NEXT_PUBLIC_으로 시작하도록 하면 됩니다.
NEXT_PUBLIC_MY_NAME=soaple
그러면 빌드 시에 Next.js에서 NEXT_PUBLIC_으로 시작하는 환경 변수를 참조하는 모든 부분의 값을 실제 값으로 치환하여 인라인으로 넣어주게 됩니다. 여기서 한 가지 유의할 점은 외부에 노출되어서는 안 되는 중요한 값(보안 키 값, DB 접속 정보 등)의 경우에는 NEXT_PUBLIC_을 사용하면 안 된다는 점입니다.
그리고 아래와 같이 변수를 사용해서 동적으로 환경 변수의 값을 가져오는 형태로는 사용할 수 없습니다.
// 변수를 사용하기 때문에 사용 불가
const varName = 'NEXT_PUBLIC_MY_NAME';
setUserName(process.env[varName]);
// 변수를 사용하기 때문에 사용 불가
const env = process.env;
setUserName(env.NEXT_PUBLIC_MY_NAME);
마지막 업데이트: 2025년 10월 24일 04시 09분
이 문서의 저작권은 이인제(소플)에 있습니다. 무단 전재와 무단 복제를 금합니다.