Environment Variables (.env 공식문서 번역하기)

Environment Variables

---

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

• .env.local 환경변수를 로드하는 데 사용
• Next.js에서 사용하는 환경 변수를 브라우저에서 사용하고 싶을 때, 해당 환경 변수의 이름에 NEXT_PUBLIC_ 이라는 접두사를 붙여 사용 가능

환경 변수 로드

---

Next.js는 기본적으로 process.env에서 .env.local 파일로부터 환경 변수를 불러오는 기능을 지원합니다.

.env.local

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

Next.js는 자동으로 process.env에 .env.local 파일의 환경 변수를 가져옵니다. 이렇게하면 Next.js의 데이터 가져오기 메서드와 API 라우트에서 사용할 수 있습니다. 예를 들어, getStaticProps를 사용하면 다음과 같이 작성할 수 있습니다.

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는 $VARIABLE을 사용하여 .env* 파일 내에서 다른 변수를 참조하도록 변수를 자동으로 확장합니다. 이렇게하면 다른 비밀 값을 참조할 수 있습니다. 예를 들면:

.env:

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

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

알아두면 좋은 점: 실제 값에 $가 필요한 변수를 사용하려면 $를 사용하여 이스케이프해야 합니다.

브라우저에 환경 변수 번들

---

<aside> 👋 NEXT_PUBLIC_ 접두사를 사용하는 환경 변수들은 Node.js 환경에서 사용할 수 있게 설정되어 있지만, 기본적으로 브라우저에서는 접근할 수 없습니다. 이는 클라이언트(브라우저) 환경과 서버(Node.js) 환경이 서로 다르기 때문입니다.

그러나 변수 이름에 NEXT_PUBLIC_ 접두사를 붙여 브라우저에서 환경 변수 값을 사용하려면, Next.js는 빌드 시간에 이 값들을 JavaScript 번들에 직접 포함(인라인)합니다. 이처럼 값을 인라인 작업을 통해 브라우저에서도 해당 환경 변수에 액세스할 수 있게 됩니다.

</aside>

예를 들면:

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

이렇게 하면 Next.js는 노드 환경에서 process.env.NEXT_PUBLIC_ANALYTICS_ID 참조를 빌드때 사용 가능한 값으로 대체합니다. 이 값을 코드에서 어디든 사용할 수 있습니다.

알아두기: 빌드 후에는 이러한 환경 변수의 변경에 대해 앱이 더 이상 응답하지 않습니다. 예를 들어 한 환경에서 빌드된 슬러그를 다른 환경으로 프로모션하는 Heroku 파이프라인을 사용하거나 도커 이미지를 여러 환경에 배포하는 경우, 모든 NEXT_PUBLIC_ 변수는 빌드 시간에 평가된 값과 함께 고정됩니다. 이 값들은 프로젝트가 빌드될 때 적절하게 설정되어야 합니다. 런타임 환경 값에 액세스가 필요한 경우 클라이언트에게 제공 할 API를 직접 설정해야 합니다.

pages/index.js:

import setupAnalyticsService from '../lib/my-analytics-service'
 
// 'NEXT_PUBLIC_ANALYTICS_ID' can be used here as it's prefixed by 'NEXT_PUBLIC_'.
// It will be transformed at build time to `setupAnalyticsService('abcdefghijk')`.
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)
 
function HomePage() {
  return <h1>Hello World</h1>
}
 
export default HomePage

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

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

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

기본 환경 변수

---

일반적으로 하나의 .env.local 파일이 필요합니다. 그러나 때로는 개발(next dev) 또는 프로덕션(next start) 환경을 위한 기본값을 추가하고 싶을 수 있습니다.

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

.env.local은 항상 설정한 기본값을 덮어씁니다.

알아두기: .env, .env.development, .env.production 파일은 기본값을 정의하기 때문에 저장소에 포함되어야 합니다. .env*.local은 .gitignore에 추가되어야 합니다.

Test 환경 변수

---

개발 환경과 프로덕션 환경 외에도 제 3의 옵션인 Test 환경이 있습니다. 개발 혹은 프로덕션 환경의 기본값을 설정하는 것처럼 .env.test 파일에서 테스트 환경에서 사용할 기본값을 설정할 수 있습니다 (그러나 이것은 앞서 언급한 두 가지와 비교하여 그리 일반적이지 않습니다).

Next.js는 테스트 환경에서 .env.development이나 .env.production의 환경 변수를 로드하지 않습니다.  이것은 jest나 cypress와 같은 도구로 테스트를 실행할 때 테스트 목적으로만 특정한 환경 변수를 설정할 필요가 있는 경우 유용합니다.

NODE_ENV가 test로 설정된 경우 테스트 기본값이 로드되지만, 테스트 도구에서 전달받기 때문에 일반적으로 이 작업을 수동으로 수행할 필요는 없습니다. 테스트 환경과 개발 및 프로덕션 환경 사이에는 분명한 차이가 있습니다.

env.local이 로드되지 않습니다. 이는 테스트 결과가 모두에 대해 동일하게 나오기를 원하기 때문입니다.

이런 방식으로 모든 테스트 실행은 다른 실행에서 동일한 환경 기본값을 사용하여 .env.local (기본값을 재정의하기 위한 것)을 무시합니다.

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

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

아래 코드는 Jest 전역 설정 파일 또는 테스트 설정과 유사하게 사용할 수 있습니다.

// 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 (Not checked when NODE_ENV is test.)
4. .env.$(NODE_ENV)
5. .env
6.  

❓ env와 env.local의 차이

.env 파일: 모든 환경(개발, 테스트, 프로덕션)에서 공통으로 사용되는 기본 환경 변수를 저장합니다. 이 파일은 프로젝트의 버전 관리 시스템(예: Git)에 포함되어야 하며, 팀원 간에 공유되는 공통 환경 설정을 저장하는 데 사용됩니다.

 

.env.local 파일: 로컬 개발 환경에만 적용되는 환경 변수를 저장합니다. 이 파일은 개발자 별로 다른 설정이 필요한 경우, 예를 들어 데이터베이스 연결 정보나 개인 API 키와 같은 민감한 정보를 저장하기에 적합합니다. .env.local 파일은 일반적으로 버전 관리 시스템에서 제외되고(예: .gitignore에 추가), 각 개발자가 로컬 환경에서만 사용할 설정을 저장합니다.