문서
App Router 사용하기
애플리케이션 구축하기
환경 설정
환경 변수

환경 변수

예시

Next.js는 환경 변수에 대한 내장 지원을 제공하여 다음과 같은 작업을 할 수 있습니다:

환경 변수 로드하기

Next.js는 .env* 파일에서 환경 변수를 process.env로 로드하는 내장 지원을 제공합니다.

.env
DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

참고: Next.js는 .env* 파일 내의 여러 줄 변수도 지원합니다:

# .env
 
# 줄 바꿈으로 작성할 수 있습니다
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
Kh9NV...
...
-----END DSA PRIVATE KEY-----"
 
# 또는 큰따옴표 안에 `\n`을 사용할 수 있습니다
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nKh9NV...\n-----END DSA PRIVATE KEY-----\n"

참고: /src 폴더를 사용하는 경우, Next.js는 .env 파일을 오직 상위 폴더에서만 로드하고 /src 폴더에서는 로드하지 않습니다. 이는 process.env.DB_HOST, process.env.DB_USER, 그리고 process.env.DB_PASS를 Node.js 환경으로 자동으로 로드하여 라우트 핸들러에서 사용할 수 있게 합니다.

예를 들어:

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

@next/env로 환경 변수 로드하기

ORM이나 테스트 도구를 위한 루트 설정 파일과 같이 Next.js 런타임 외부에서 환경 변수를 로드해야 하는 경우, @next/env 패키지를 사용할 수 있습니다.

이 패키지는 Next.js에서 내부적으로 .env* 파일에서 환경 변수를 로드하는 데 사용됩니다.

사용하려면 패키지를 설치하고 loadEnvConfig 함수를 사용하여 환경 변수를 로드하세요:

npm install @next/env
envConfig.ts
import { loadEnvConfig } from "@next/env";
 
const projectDir = process.cwd();
loadEnvConfig(projectDir);
envConfig.js
import { loadEnvConfig } from "@next/env";
 
const projectDir = process.cwd();
loadEnvConfig(projectDir);

그런 다음 필요한 곳에서 설정을 가져올 수 있습니다. 예를 들어:

orm.config.ts
import "./envConfig.ts";
 
export default defineConfig({
  dbCredentials: {
    connectionString: process.env.DATABASE_URL!,
  },
});
orm.config.js
import "./envConfig.js";
 
export default defineConfig({
  dbCredentials: {
    connectionString: process.env.DATABASE_URL,
  },
});

다른 변수 참조하기

Next.js는 .env* 파일 내에서 $를 사용하여 다른 변수를 참조하는 변수를 자동으로 확장합니다. 이를 통해 다른 비밀을 참조할 수 있습니다. 예를 들어:

.env
TWITTER_USER=nextjs
TWITTER_URL=https://x.com/$TWITTER_USER

위의 예에서 process.env.TWITTER_URL은 https://x.com/nextjs로 설정됩니다.

알아두면 좋은 점: 실제 값에 $를 포함하는 변수를 사용해야 하는 경우, \$로 이스케이프 처리해야 합니다.

브라우저용 환경 변수 번들링하기

NEXT_PUBLIC_가 아닌 환경 변수는 Node.js 환경에서만 사용할 수 있으며, 브라우저에서는 접근할 수 없습니다(클라이언트는 다른 환경에서 실행됩니다).

환경 변수의 값을 브라우저에서 접근할 수 있게 하려면 Next.js는 빌드 시에 값을 클라이언트에 전달되는 js 번들에 "인라인"할 수 있으며, process.env.[변수]에 대한 모든 참조를 하드코딩된 값으로 대체합니다. 이를 수행하도록 지시하려면 변수 앞에 NEXT_PUBLIC_를 붙이면 됩니다. 예를 들어:

Terminal
NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

이는 Next.js에게 Node.js 환경에서 process.env.NEXT_PUBLIC_ANALYTICS_ID에 대한 모든 참조를 next build를 실행하는 환경의 값으로 대체하도록 지시하여 코드의 어디에서나 사용할 수 있게 합니다. 브라우저로 전송되는 모든 JavaScript에 인라인됩니다.

참고: 빌드된 후에는 앱이 더 이상 이러한 환경 변수의 변경에 반응하지 않습니다. 예를 들어, Heroku 파이프라인을 사용하여 한 환경에서 빌드된 슬러그를 다른 환경으로 승격시키거나, 단일 Docker 이미지를 여러 환경에 빌드하고 배포하는 경우, 모든 NEXT_PUBLIC_ 변수는 빌드 시 평가된 값으로 고정됩니다. 따라서 이러한 값들은 프로젝트가 빌드될 때 적절하게 설정되어야 합니다. 런타임 환경 값에 접근해야 하는 경우, 클라이언트에 이를 제공하기 위한 자체 API를 설정해야 합니다(요청 시 또는 초기화 중에).

pages/index.js
import setupAnalyticsService from "../lib/my-analytics-service";
 
// 'NEXT_PUBLIC_ANALYTICS_ID'는 'NEXT_PUBLIC_'로 시작하므로 여기서 사용할 수 있습니다.
// 빌드 시 `setupAnalyticsService('abcdefghijk')`로 변환됩니다.
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID);
 
function HomePage() {
  return <h1>Hello World</h1>;
}
 
export default HomePage;

동적 조회는 인라인되지 않습니다. 예를 들어:

// 변수를 사용하므로 인라인되지 않습니다
const varName = "NEXT_PUBLIC_ANALYTICS_ID";
setupAnalyticsService(process.env[varName]);
 
// 변수를 사용하므로 인라인되지 않습니다
const env = process.env;
setupAnalyticsService(env.NEXT_PUBLIC_ANALYTICS_ID);

런타임 환경 변수

Next.js는 빌드 시간과 런타임 환경 변수를 모두 지원할 수 있습니다.

기본적으로 환경 변수는 서버에서만 사용할 수 있습니다. 환경 변수를 브라우저에 노출하려면 NEXT_PUBLIC_로 시작해야 합니다. 그러나 이러한 공개 환경 변수는 next build 중에 JavaScript 번들에 인라인됩니다.

런타임 환경 변수를 읽으려면 getServerSideProps를 사용하거나 App Router를 점진적으로 채택하는 것이 좋습니다. App Router를 사용하면 동적 렌더링 중에 서버에서 안전하게 환경 변수를 읽을 수 있습니다. 이를 통해 다른 값을 가진 여러 환경에서 승격될 수 있는 단일 Docker 이미지를 사용할 수 있습니다.

import { unstable_noStore as noStore } from "next/cache";
 
export default function Component() {
  noStore();
  // cookies(), headers() 및 기타 동적 함수도
  // 동적 렌더링으로 전환되어
  // 이 환경 변수가 런타임에 평가됩니다
  const value = process.env.MY_VALUE;
  // ...
}

알아두면 좋은 점:

  • register 함수를 사용하여 서버 시작 시 코드를 실행할 수 있습니다.
  • runtimeConfig 옵션을 사용하는 것은 권장하지 않습니다. 이는 독립 실행형 출력 모드에서 작동하지 않기 때문입니다. 대신 App Router를 점진적으로 채택하는 것을 권장합니다.

기본 환경 변수

일반적으로 .env* 파일 하나만 필요합니다. 그러나 때로는 development(next dev) 또는 production(next start) 환경에 대한 기본값을 추가하고 싶을 수 있습니다.

Next.js는 .env(모든 환경), .env.development(개발 환경), .env.production(프로덕션 환경)에서 기본값을 설정할 수 있습니다.

알아두면 좋은 점: .env, .env.development, .env.production 파일은 기본값을 정의하므로 리포지토리에 포함되어야 합니다. 모든 .env 파일은 기본적으로 .gitignore에서 제외되므로 이러한 값을 리포지토리에 커밋하도록 선택할 수 있습니다.

Vercel의 환경 변수

Next.js 애플리케이션을 Vercel에 배포할 때, 환경 변수는 프로젝트 설정에서 구성할 수 있습니다.

모든 유형의 환경 변수는 프로젝트 설정에서 구성되어야 합니다. 개발에 사용되는 환경 변수도 마찬가지이며, 이는 나중에 로컬 기기로 다운로드할 수 있습니다.

개발 환경 변수를 구성한 경우 다음 명령을 사용하여 로컬 머신에서 사용할 수 있도록 .env.local로 가져올 수 있습니다:

Terminal
vercel env pull

알아두면 좋은 점: Next.js 애플리케이션을 Vercel에 배포할 때, .env* 파일의 환경 변수는 이름이 NEXT_PUBLIC_로 시작하지 않는 한 Edge Runtime에서 사용할 수 없습니다. 대신 프로젝트 설정에서 환경 변수를 관리하는 것을 강력히 권장합니다. 여기서 모든 환경 변수를 사용할 수 있습니다.

테스트 환경 변수

development와 production 환경 외에도 세 번째 옵션인 test가 있습니다. 개발이나 프로덕션 환경에 대한 기본값을 설정할 수 있는 것과 같은 방식으로 .env.test 파일을 사용하여 testing 환경에 대한 기본값을 설정할 수 있습니다(이 옵션은 이전 두 옵션만큼 일반적이지는 않습니다). Next.js는 testing 환경에서 .env.development 또는 .env.production의 환경 변수를 로드하지 않습니다.

이는 jest나 cypress와 같은 도구로 테스트를 실행할 때 테스트 목적으로만 특정 환경 변수를 설정해야 하는 경우에 유용합니다. NODE_ENV가 test로 설정되면 테스트 기본값이 로드되지만, 일반적으로 테스트 도구가 이를 처리하므로 수동으로 설정할 필요는 없습니다.

test 환경과 development 및 production 환경 사이에는 유의해야 할 작은 차이가 있습니다: .env.local이 로드되지 않습니다. 이는 테스트가 모든 사람에게 동일한 결과를 생성해야 한다고 예상하기 때문입니다. 이렇게 하면 .env.local(기본 세트를 재정의하기 위한 것)을 무시함으로써 모든 테스트 실행이 다른 실행 간에 동일한 환경 기본값을 사용하게 됩니다.

알아두면 좋은 점: 기본 환경 변수와 마찬가지로 .env.test 파일은 리포지토리에 포함되어야 하지만 .env.test.local은 포함되지 않아야 합니다. .env*.local은 .gitignore를 통해 무시되도록 되어 있습니다.

단위 테스트를 실행할 때 @next/env 패키지의 loadEnvConfig 함수를 활용하여 Next.js와 동일한 방식으로 환경 변수를 로드할 수 있습니다.

// 아래 내용은 Jest 전역 설정 파일이나 유사한 테스트 설정에서 사용할 수 있습니다
import { loadEnvConfig } from "@next/env";
 
export default async () => {
  const projectDir = process.cwd();
  loadEnvConfig(projectDir);
};

환경 변수 로드 순서

환경 변수는 다음 순서로 조회되며, 변수가 발견되면 검색이 중단됩니다.

  1. process.env
  2. .env.$(NODE_ENV).local
  3. .env.local (NODE_ENV가 test일 때는 확인하지 않습니다.)
  4. .env.$(NODE_ENV)
  5. .env

예를 들어, NODE_ENV가 development이고 .env.development.local과 .env 모두에서 변수를 정의한 경우 .env.development.local의 값이 사용됩니다.

알아두면 좋은 점: NODE_ENV에 허용되는 값은 production, development, test입니다.

알아두면 좋은 점

  • /src 디렉토리를 사용하는 경우, .env.* 파일은 프로젝트의 루트에 남아 있어야 합니다.
  • 환경 변수 NODE_ENV가 할당되지 않은 경우, Next.js는 next dev 명령을 실행할 때 자동으로 development를, 다른 모든 명령에 대해서는 production을 할당합니다.

버전 기록

버전변경 사항
v9.4.0.env와 NEXT_PUBLIC_ 지원이 도입되었습니다.
ESLint절대 경로 import 및 모듈 경로 별칭