Next.js 12-3 Configuring Environment Variables

  Nest.js는 환경 변수에 대한 기본 제공 지원을 제공하므로 다음을 수행할 수 있다.

1. env.local을 사용하여 환경 변수를 로드한다.
2. NEXT_PUBLIC_ 접두사를 사용하여 브라우저에 대한 번들 환경 변수를 제공한다.

 

• Loading Environment Variables

  Next.js는 .env.local에서 process.env로 환경 변수를 로드하는 기능을 기본적으로 지원한다.

// .env.local

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

  이렇게 하면 process.env.DB_HOST, process.DB_USER와 process.env.DB_PASS가 Node.js 환경에 자동으로 로드되어 경로 처리기에서 사용할 수 있다.

 

• 다른 변수 참조하기

  Next.js $를 사용하여 다른 변수를 참조하는 변수를 자동으로 확장한다(.env* 파일 내부의 $VARIABLE). 이렇게 하면 다른 암호들도 참조할 수 있다. 예를 들면,

// .env

TWITTER_USER=nextjs
TWITTER_URL=https://twitter.com/$TWITTER_USER

  위의 예에서 process.env.TWITTER_URL은 https://twitter.com/nextjs로 설정된다. 만약 실제 값에 $가 있는 변수를 사용해야 하는 경우에는 이스케이프해야 한다. \$ 

 

• 브라우저 번들 환경 변수

  Non-NEXT_PUBLIC_ 환경 변수는 Node.js 환경에서만 사용할 수 있다. 즉, 브라우저에서 액세스 할 수 없다(클라이언트는 다른 환경에서 실행됨).

  브라우저에서 환경 변수의 값에 액세스할 수 있도록 하려면, Next.js는 빌드 시 클라이언트에 전달되는 js 번들에 값을 "인라인"하여 process.env.[variable]에 대한 모든 참조를 하드 코딩된 값으로 대체할 수 있다. 이렇게 하라고 지시하려면 변수에 NEXT_PUBLIC_ 접두사를 붙이기만 하면 된다. 

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

  이렇게 하면 Node.js 환경의 process.env.NEXT_PUBLIC_ANALYTICS_ID에 대한 모든 참조를 다음 빌드를 실행하는 환경의 값으로 바꾸도록 Next.js에 지시한다. 코드의 어느 곳에서나 사용할 수 있다. 브라우저로 전송되는 모든 JavaScript에 인라인 된다.

  앱이 빌드된 후에는 이러한 환경 변수에 대한 변경 사항에 더 이상 응답하지 않는다. 예를 들어 Heroku 파이프라인을 사용하여 한 환경에서 빌드된 슬러그를 다른 환경으로 승격하거나 단일 Docker 이미지를 빌드하여 여러 환경에 배포하는 경우 모든 NEXT_PUBLIC_ 변수는 빌드 시 평가된 값으로 고정되므로 이러한 값은 프로젝트를 빌드할 때 적절하게 설정해야 한다. 런타임 환경 값에 액세스해야 하는 경우 요청 시 또는 초기화 중에 클라이언트에 제공하도록 자체 API를 설정해야 한다.

// pages/index.js

import setupAnalyticsService from '../lib/my-analytics-service'

// 'NEXT_PUBLIC_ANALYTICS_ID' can be used here as is's prefixed by 'NEXT_PUBLIC_'.
// It will be transformed at build time to `serupAnalyticsService('abcdefghijk')`.
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)

function HomePage() {
  return <h1>Hello World</h1>
}

export default HomePage

  다음과 같은 동적 조회는 인라인 되지 않는다.

// This will NOT be inlined, because if uses a variable
const varName = 'NEXT_PUBLIC_ANALYTICS_ID'
setupAnalyticsService(process.env[varName])

// This will NOT be inlined, because if uses a variable
const env = process.env
setupAnalyticsService(env.NEXT_PUBLIC_ANALYTICS_ID)

 

• Default Environment Variables

  일반적으로 하나의 .env.local 파일만 필요한다. 그러나 때로는 개발(next dev) 또는 프로덕션(next start) 환경에 대한 일부 기본값을 추가해야 할 수도 있다.

  Next.js를 사용하면 .env(모든 환경), .env.development(개발 환경) 및 .env.production(프로덕션 환경)에서 기본값을 설정할 수 있다. .env.local은 항상 기본값 세트를 재정의한다.

  .env .env.development와 .env.production 파일은 기본값을 정의하므로 저장소에 포함되어야 한다. .env*.local은 무시할 파일이므로 .gitignore에 추가해야 한다. .env.local은 비밀을 저장할 수 있는 곳이다.

 

• Vercel의 환경 변수

  Next.js 애플리케이션을 Vercel에 배포할 때 프로젝트 설정에서 환경 변수를 구성할 수 있다. 모든 유형의 환경 변수를 여기에서 구성해야 한다. 개발에 사용되는 환경 변수도 나중에 로컬 장치에 다운로드할 수 있다. 개발 환경 변수를 구성한 경우 다음 명령을 사용하여 로컬 컴퓨터에서 사용할 수 있도록 .env.local로 가져올 수 있다.

vercel env pull .env.local

 

• 테스트 환경 변수

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

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

  테스트 환경과 개발 및 프로덕션 사이에는 약간의 차이가 있다. 명심해야 할 사항은 .env.local 테스트가 모든 사람에게 동일한 결과를 생성할 것으로 예상하기 때문에 로드되지 않는다는 것이다. 이 방법은 모든 테스트 실행은 .env.local(기본 세트를 재정의하기 위한 것임)을 무시함으로써 서로 다른 실행에서 동일한 환경 기본값을 사용한다.

  기본 환경 변수와 마찬가지로 .env.test 파일은 레포지토리에 포함되어야 하지만 .env.test.local은 포함되지 않아야 한다. .env*.local은 .gitignore를 통해 무시되도록 의도되었기 때문이다.

  단위 테스트를 실행하는 동안 @next.env 패키지의 loadEnvConfig 기능을 활용하여 Next.js와 동일한 방식으로 환경 변수를 로드할 수 있다.

// The below can be used in a Jest global setup file or similar for your testing set-up
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가 테스트일 때는 확인되지 않는다.)
4. .env.$(NODE_ENV)
5. .env

  예를 들어 NODE_ENV가 development이고 .env.development.local과 .env 모두에 변수를 정의하면 .env.development.local의 값이 사용된다.