Next.js env(환경 변수) 정리

milkboy2564·2023년 3월 28일
20

환경 변수

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

환경 변수 로드

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 환경에서 환경 변수를 로드하지 않습니다.

이 방법은 jestcypress와 같은 도구로 테스트를 실행할 때 특정 환경 변수를 설정해야 하는 경우에 유용합니다. 테스트 기본값이 로드됩니다. NODE_ENVtest로 설정된 경우, 하지만 대개 테스트 도구가 이를 대신 처리합니다.

test 환경, developmentproduction 간의 차이점이 있으므로 .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_ENVdevelopment이고 .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는 널리 사용되는 폴리필을 삽입합니다.

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

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

사용자 정의 폴리필

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

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

JavaScript 언어 기능

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

서버 측 폴리필

클라이언트 측에서 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 는 애플리케이션 내에서 문제가 발생할 수 있는 부분에 대해 경고를 알려주는 기능입니다.

swcMinifyTerser와 비슷한 역할을 합니다. 필요 없는 코드나 공백, 변수명을 없애거나 줄여서 번들링 되는 자바스크립트 파일의 크기를 줄여주는 역할을 합니다. 즉, 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 속성

참고

profile
FE 개발자

2개의 댓글

comment-user-thumbnail
2024년 1월 26일

너무 유익합니다 :)

답글 달기
comment-user-thumbnail
2024년 1월 29일

좋은 내용 감사합니다.

답글 달기