환경 변수

Next.js는 환경 변수를 내장하고 있어 다음을 수행할 수 있습니다.

• .env.local를 사용하여 환경 변수 로드
• 브라우저에 NEXT_PUBLIC_를 접두사로 사용하여 환경 변수 노출

환경 변수 로드

Next.js는 내장된 .env.local에서 환경 변수를 process.env로 로드할 수 있는 기능을 제공합니다.

예를 들어 .env.local:

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

이는 process.env.DB_HOST, process.env.DB_USER, process.env.DB_PASS를 Node.js 환경에 자동으로 로드하여 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,
  })
  // ...
}

참고: server-only-secrets은 안전하게 유지하기 위해 환경 변수는 빌드 시 평가되므로 실제로 사용되는 환경 변수만 포함됩니다. 이는 process.env가 표준 JavaScript 객체가 아니므로 객체 구조 분해를 사용할 수 없다는 것을 의미합니다. 환경 변수는 process.env.PUBLISHABLE_KEY 등으로 참조해야 합니다.

참고: Next.js는 .env* 파일 내부의 변수($VAR)를 자동으로 확장합니다. 이를 사용하여 다른 secret을 참조할 수 있습니다.

# .env
HOSTNAME=localhost
PORT=8080
HOST=http://$HOSTNAME:$PORT

실제 값에 $가 있는 변수를 사용하려면 다음과 같이 이스케이프해야 합니다: \\ $.

예를 들어:

# .env
A=abc

# becomes "preabc"
WRONG=pre$A

# becomes "pre$A"
CORRECT=pre\\$A

참고: /src 폴더를 사용하는 경우 Next.js는 .env 파일을 상위 폴더에서만 로드하고 /src 폴더에서는 로드하지 않습니다.

브라우저에 환경 변수 노출

기본적으로 환경 변수는 브라우저에 표시되지 않기 때문에 Node.js 환경에서만 사용할 수 있습니다.

브라우저에 변수를 노출하려면 변수를 NEXT_PUBLIC_로 접두사를 붙여야 합니다. 예를 들면:

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

이는 process.env.NEXT_PUBLIC_ANALYTICS_ID를 Node.js 환경에 자동으로 로드하여 코드의 어디에서든 사용할 수 있게 합니다. 값은 NEXT_PUBLIC_ 접두사 때문에 브라우저로 전송되는 JavaScript에 인라인됩니다. 이 인라인은 빌드 시 발생하므로 프로젝트 빌드 시 NEXT_PUBLIC_ 환경이 설정되어 있어야 합니다.

// 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은 무시되어야 합니다. .env.local에 secrets을 저장할 수 있습니다.

Vercel의 환경 변수

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

모든 유형의 환경 변수를 구성해야 합니다. 개발에 사용되는 환경 변수도 다운로드하여 이후에 로컬 기기에서 사용할 수 있습니다.

개발 환경 변수를 구성했다면 다음 명령을 사용하여 .env.local에서 사용할 수 있습니다.

vercel env pull .env.local

테스트 환경 변수

개발 및 프로덕션 환경 외에 test라는 3번째 옵션이 있습니다. 개발이나 프로덕션 환경에 기본값을 설정할 수 있는 것처럼, testing 환경을 위한 .env.test 파일을 사용하여 동일한 작업을 수행할 수 있습니다. 이 방법은 이전 두 가지 방법보다는 일반적이지 않습니다. Next.js는 .env.development 또는 .env.production에서 testing 환경에서 환경 변수를 로드하지 않습니다.

이 방법은 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가 환경 변수를 로드하는 방식과 동일하게 환경 변수를 로드할 수 있습니다.

// 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가 test인 경우 확인되지 않음.)
4. .env.$(NODE_ENV)
5. .env

예를 들어 NODE_ENV가 development이고 .env.development.local 및 .env에서 변수를 정의하면 .env.development.local의 값이 사용됩니다.

참고: NODE_ENV의 허용된 값은 production, development, test입니다.

---

지원되는 브라우저 및 기능

Next.js는 구성 없이 최신 브라우저를 지원합니다.

• Chrome 64+
• Edge 79+
• Firefox 67+
• Opera 51+
• Safari 12+

Browserslist

특정 브라우저나 기능을 대상으로 하려면, Next.js는 package.json 파일에서 Browserslist 구성을 지원합니다. Next.js는 다음과 같은 Browserslist 구성을 기본적으로 사용합니다.

{
  "browserslist": [
    "chrome 64",
    "edge 79",
    "firefox 67",
    "opera 51",
    "safari 12"
  ]
}

폴리필

Next.js는 널리 사용되는 폴리필을 삽입합니다.

• fetch() — 대체: whatwg-fetch and unfetch.
• URL — 대체: the [url package (Node.js API)](https://nodejs.org/api/url.html).
• Object.assign() — 대체: object-assign, object.assign, and core-js/object/assign.

이러한 폴리필 중 하나라도 종속성에 포함되어 있으면, 중복을 피하기 위해 제작 빌드에서 자동으로 제거됩니다.

또한 번들 크기를 줄이기 위해, Next.js는 필요한 브라우저에서만 이러한 폴리필을 로드합니다. 전 세계 대부분의 웹 트래픽은 이러한 폴리필을 다운로드하지 않습니다.

사용자 정의 폴리필

대상 브라우저(예: IE 11)에서 지원되지 않는 기능이 필요한 경우, 사용자 정의 폴리필을 추가해야 합니다.

이 경우에는 사용자 정의 <App> 또는 개별 컴포넌트에서 필요한 특정 폴리필을 상위 수준에서 가져와야 합니다.

JavaScript 언어 기능

Next.js를 사용하면 최신 JavaScript 기능을 쉽게 사용할 수 있습니다. ES6 기능 외에도 Next.js는 다음을 지원합니다.

• Async/await (ES2017)
• Object Rest/Spread Properties (ES2018)
• Dynamic import() (ES2020)
• Optional Chaining (ES2020)
• Nullish Coalescing (ES2020)
• Class Fields and Static Properties (stage 3 proposal의 일부)
• 그 외 많은 기능들!

서버 측 폴리필

클라이언트 측에서 fetch() 뿐만 아니라, Next.js는 Node.js 환경에서도 fetch() 폴리필을 지원합니다. 따라서 isomorphic-unfetch 또는 node-fetch 와 같은 폴리필 없이 서버 측 코드(예: getStaticProps/getServerSideProps)에서 fetch() 를 사용할 수 있습니다.

---

React

1. .env.local (로컬 개발 시)

.env.local 파일은 .env를 덮어쓰는 파일로, test 환경 외의 모든 환경에서 로딩됩니다.

2. .env.development

.env.development 파일은 개발환경 시 아래의 명령어를 치면 사용됩니다. 만약, .env.development.local이 있다면, .env.development을 덮어 씁니다.

$ npm run start
$ yarn start

npm start 시 .env 파일도 실행되는 우선순위가 있습니다. 우선순위는 아래와 같습니다.

.env.development.local > .env.development > .env.local > .env

3. .env.production (서버 배포 시)

.env.production 파일은 배포 환경 시 사용되며, 아래의 명령어를 치면 자동으로 사용됩니다. 만약, .env.production.local이 있다면, .env.production을 덮어씁니다.

$ npm run build
$ yarn build

npm run build 시 .env 파일도 실행되는 우선순위가 있습니다. 우선순위는 아래와 같습니다.

.env.production .local > .env.production > .env.local > .env

4. .env.test

.env.test 파일은 테스트 환경 시 사용합니다. 만약, .env.test.local이 있다면, .env.test을 덮어쓴다.

$ npm run test$ yarn test

npm run test시 .env 파일도 실행되는 우선순위가 있다. 우선순위는 아래와 같다.

.env.test.local > .env.test> .env.local > .env

5. prefix

리액트에서 .env 환경 설정 시 변수명에 REACT_APP_이라고 앞에 붙여줘야 인식을 합니다. 만약 붙이지 않으면 무시합니다.

Next

1. React

.env.* 와 같은 형식으로 환경 변수를 설정하는 방식은 React와 동일하고 우선 순위 또한 동일하게 동작합니다.
하지만 브라우저에서 환경 변수를 사용할 때, 환경 변수 앞에 붙는 prefix가 다른데 React는 REACT_APP_, Next는 NEXT_PUBLIC_ 을 붙여줘야 정상적으로 환경 변수를 인식합니다.

2. next.config.js

기본적으로 npx create-next-app@latest 로 Next 프로젝트를 생성하면 아래와 같이 next.config.js 파일이 함께 생성됩니다.

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  swcMinify: true,
};

module.exports = nextConfig;

reactStrictMode 는 애플리케이션 내에서 문제가 발생할 수 있는 부분에 대해 경고를 알려주는 기능입니다.

swcMinify 는 Terser와 비슷한 역할을 합니다. 필요 없는 코드나 공백, 변수명을 없애거나 줄여서 번들링 되는 자바스크립트 파일의 크기를 줄여주는 역할을 합니다. 즉, Minifying을 해주는 역할입니다.

next.config.js 파일은 함수로도 구성할 수 있습니다.

// 일반 함수 사용
module.exports = (phase, { defaultConfig }) => {
  const nextConfig = {
    /* config options here */
  }
  return nextConfig
}

// async 함수 사용
module.exports = async (phase, { defaultConfig }) => {
  const nextConfig = {
    /* config options here */
  }
  return nextConfig
}

인자로 들어오는 phase 는 설정 환경을 의미합니다. phase 에 들어올 수 있는 환경은 여기에서 확인할 수 있습니다.

phase 를 사용하는 기본 구성은 아래와 같습니다.

const { PHASE_DEVELOPMENT_SERVER } = require('next/constants')

module.exports = (phase, { defaultConfig }) => {
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      /* 개발 환경 설정 구성 */
    }
  }

  return {
    /* 개발 환경 제외한 환경 설정 구성 */
  }
}

설정이 가능한 next.config 파일의 속성은 여기서 확인할 수 있습니다.

Vite

1. import.meta.env

Next나 React가 환경 변수에 접근할 때 process.env 객체에서 접근하는 것과 다르게 import.meta.env 객체에서 환경 변수에 접근할 수 있습니다.

• import.meta.env.MODE: {string} 현재 앱이 동작하고 있는 모드
• import.meta.env.BASE_URL: {string} 앱이 제공되는 베이스 URL이며, 이 값은 base 설정에 의해 결정
• import.meta.env.PROD: {boolean} 앱이 프로덕션에서 실행 중인지 여부.
• import.meta.env.DEV: {boolean} 앱이 개발 환경에서 실행 중인지 여부이며, 항상 import.meta.env.PROD와 반대되는 값
• import.meta.env.SSR: {boolean} 앱이 서버에서 실행 중인지 여부

2. 정적 참조

React, Next, Vite 모두 환경 변수는 정적으로 참조되어야만 합니다.

예를 들어 import.meta.env[key] 와 같은 형식은 동작하지 않습니다.

3. HMR

환경 변수는 로컬 서버가 변경을 감지하지 못해 HMR 적용 대상이 아닙니다. 따라서 개발 서버(로컬 서버)가 구동 되는 상황에서 변경이 되었다면 개발 서버를 재시작 해야합니다.

---

환경 변수 우선 순위 정리

React

환경 변수의 우선 순위는 다음과 같습니다.

• 컴퓨터 전역 환경 변수
• .env.local 파일
• .env.${NODE_ENV}.local 파일
• .env.${NODE_ENV} 파일
• .env 파일
• REACT_APP_으로 시작하는 환경 변수

Vite

환경 변수의 우선 순위는 다음과 같습니다.

• 컴퓨터 전역 환경 변수
• .env.development.local 파일
• .env.local 파일
• .env.${mode}.local 파일
• .env.${mode} 파일
• .env 파일
• Vite 설정 파일 (vite.config.js)의 env 속성

Next.js

환경 변수의 우선 순위는 다음과 같습니다.

• 컴퓨터 전역 환경 변수
• .env.local 파일
• .env.${NODE_ENV}.local 파일
• .env.${NODE_ENV} 파일
• .env 파일
• Next.js 설정 파일 (next.config.js)의 env 속성

---

참고

• https://nextjs.org/docs/api-reference/next.config.js/environment-variables
• https://vitejs-kr.github.io/guide/env-and-mode.html
• https://han-py.tistory.com/507