env 설정하기 (Next.js 9.4 버전 이후)

Next.js 9.4 버전부터는 환경 변수(environment variables)를 다루는 게 훨씬 직관적이고 편리해졌어요. 실제로 프로젝트에 적용해보면 훨씬 깔끔하게 환경 변수를 관리할 수 있답니다. 한번 사용해보세요!

여기서 설정한 환경 변수들은 모두 JavaScript 번들에 포함됩니다.
NEXT_PUBLIC_ 접두어(prefix)를 붙이는 건 환경 변수나 .env 파일을 통해 지정할 때만 의미가 있어요.
즉, next.config.js의 env 필드에 설정된 변수들은 모두 클라이언트와 서버 어디서든 접근 가능하니까, 민감한 정보는 넣지 말아야 해요!

next.config.js 파일을 열고, env 설정을 추가해줍니다.

// next.config.js
module.exports = {
  env: {
    CUSTOM_KEY: 'my-value',
    ANOTHER_KEY: 'another-value',
  },
}

위와 같이 설정하면, 앱 전역에서 process.env.CUSTOM_KEY나 process.env.ANOTHER_KEY로 값을 사용할 수 있어요.

.env 파일에 NEXT_PUBLIC_ 접두어가 붙은 변수는 클라이언트에서도 접근 가능해요.
next.config.js에 직접 추가한 env 변수들은 처음에 말씀드린 대로, 모두 번들에 포함되어 클라이언트와 서버 모두에서 볼 수 있어요.
가급적이면 민감한 정보를 다룰 때는 서버 전용이나 런타임에 주입하는 방식으로 하는 걸 추천합니다.

개발 시에는 .env.local 파일에 환경 변수를 넣고, 빌드 시에만 next.config.js에서 값을 덮어쓰는 방식을 많이 씁니다.
process.env를 사용해서 접근할 때, 타입스크립트를 쓴다면 next-env.d.ts에서 타입 선언도 해두면 편리하답니다.
환경 변수를 바꾸고 나면 서버 재시작이 필요하다는 점 잊지 마세요!

어렵지 않으니 한번 적용해보고, 번거로운 환경 변수 관리에서 자유로워져봅시다!

Next.js에서 환경변수를 설정하는 방법에 대해 알아볼게요. 위 코드처럼 next.config.js 파일에 이렇게 작성할 수 있어요:

module.exports = {
  env: {
    customKey: 'my-value',
  },
}

그러면 앱 어디에서든 process.env.customKey로 값을 가져올 수 있답니다. 예를 들어, 컴포넌트에서 이렇게 사용할 수 있어요:

function Page() {
  return <h1>The value of customKey is: {process.env.customKey}</h1>
}

export default Page

Next.js는 빌드 타임에 process.env.customKey를 'my-value'로 알아서 바꿔주기 때문에 실제 런타임에 특별한 설정 없이도 값을 쓸 수 있어요.

여기서 주의할 점!

process.env를 구조 분해할당(destructuring)으로 쓰는 건 안 돼요. 예를 들어:

const { customKey } = process.env; // 이런 식은 동작하지 않아요!

이유는 Next.js가 내부적으로 webpack의 DefinePlugin을 사용해서 환경변수를 빌드 타임에 직접 소스코드에 치환하기 때문인데요, 구조 분해할당을 하면 변수 치환이 제대로 안 되거든요.

또 한가지 팁!

만약 보안이 필요한 비밀 키(secret key) 같은 값을 환경변수에 넣고 싶다면, env 옵션보다 .env 파일과 next.config.js의 dotenv 설정을 이용하는 게 더 안전해요.
또한, Next.js 9.4 이상부터는 .env.local, .env.development, .env.production 같은 파일을 통해 환경변수를 관리할 수 있어서 좀 더 편리해졌답니다.

이 외에도 공식 문서에서 Environment Variables를 참고하면 도움이 많이 될 거예요!

예를 들어, 아래와 같은 코드가 있다고 해볼게요:

return <h1>The value of customKey is: {process.env.customKey}</h1>

이 코드는 실제로 실행될 때 이렇게 바뀌게 됩니다:

return <h1>The value of customKey is: {'my-value'}</h1>

여기서 중요한 점은, process.env.customKey가 런타임 환경변수에서 읽히는 게 아니라, 빌드 타임에 실제 값이 주입된다는 거예요. 그래서 결국 문자열 'my-value'가 JSX에 직접 들어가게 되는 거죠.

추가로, 리액트 같은 프론트엔드 프레임워크에서 환경 변수를 사용할 때는 보통 .env 파일에 변수를 선언하고, 변수명 앞에 REACT_APP_ (또는 사용하는 프레임워크 규칙에 따라) 접두사를 붙여야 잘 인식되는 경우가 많습니다. 예를 들어:

REACT_APP_CUSTOM_KEY=my-value

그리고 코드에서는 이렇게 씁니다:

return <h1>The value of customKey is: {process.env.REACT_APP_CUSTOM_KEY}</h1>

환경변수를 이렇게 사용하면, 빌드 시점에 안전하게 값이 들어가고, 코드상에서는 직접 하드코딩하지 않아도 돼서 유지보수도 편리해집니다.

참고로, 환경변수는 보안에 민감할 수 있으니 백엔드에만 필요한 시크릿 값들은 프론트엔드에 노출되지 않도록 주의하는 게 좋습니다!

Next.js 15 환경변수(env) 설정 방법