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을 저장할 수 있습니다.
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)
}
환경 변수는 다음 순서로 검색되며, 변수가 찾아지면 중지됩니다.
process.env
.env.$(NODE_ENV).local
.env.local
(NODE_ENV가 test
인 경우 확인되지 않음.).env.$(NODE_ENV)
.env
예를 들어 NODE_ENV
가 development
이고 .env.development.local
및 .env
에서 변수를 정의하면 .env.development.local
의 값이 사용됩니다.
참고: NODE_ENV의 허용된 값은 production, development, test입니다.
Next.js는 구성 없이 최신 브라우저를 지원합니다.
특정 브라우저나 기능을 대상으로 하려면, Next.js는 package.json
파일에서 Browserslist 구성을 지원합니다. Next.js는 다음과 같은 Browserslist 구성을 기본적으로 사용합니다.
{
"browserslist": [
"chrome 64",
"edge 79",
"firefox 67",
"opera 51",
"safari 12"
]
}
Next.js는 널리 사용되는 폴리필을 삽입합니다.
whatwg-fetch
and unfetch
.[url
package (Node.js API)](https://nodejs.org/api/url.html).object-assign
, object.assign
, and core-js/object/assign
.이러한 폴리필 중 하나라도 종속성에 포함되어 있으면, 중복을 피하기 위해 제작 빌드에서 자동으로 제거됩니다.
또한 번들 크기를 줄이기 위해, Next.js는 필요한 브라우저에서만 이러한 폴리필을 로드합니다. 전 세계 대부분의 웹 트래픽은 이러한 폴리필을 다운로드하지 않습니다.
대상 브라우저(예: IE 11)에서 지원되지 않는 기능이 필요한 경우, 사용자 정의 폴리필을 추가해야 합니다.
이 경우에는 사용자 정의 <App>
또는 개별 컴포넌트에서 필요한 특정 폴리필을 상위 수준에서 가져와야 합니다.
Next.js를 사용하면 최신 JavaScript 기능을 쉽게 사용할 수 있습니다. ES6 기능 외에도 Next.js는 다음을 지원합니다.
import()
(ES2020)클라이언트 측에서 fetch()
뿐만 아니라, Next.js는 Node.js 환경에서도 fetch()
폴리필을 지원합니다. 따라서 isomorphic-unfetch
또는 node-fetch
와 같은 폴리필 없이 서버 측 코드(예: getStaticProps
/getServerSideProps
)에서 fetch()
를 사용할 수 있습니다.
.env.local
파일은 .env
를 덮어쓰는 파일로, test 환경 외의 모든 환경에서 로딩됩니다.
.env.development
파일은 개발환경 시 아래의 명령어를 치면 사용됩니다. 만약, .env.development.local
이 있다면, .env.development
을 덮어 씁니다.
$ npm run start
$ yarn start
npm start 시 .env
파일도 실행되는 우선순위가 있습니다. 우선순위는 아래와 같습니다.
.env.development.local
> .env.development
> .env.local
> .env
.env.production
파일은 배포 환경 시 사용되며, 아래의 명령어를 치면 자동으로 사용됩니다. 만약, .env.production.local
이 있다면, .env.production
을 덮어씁니다.
$ npm run build
$ yarn build
npm run build 시 .env
파일도 실행되는 우선순위가 있습니다. 우선순위는 아래와 같습니다.
.env.production .local
> .env.production
> .env.local
> .env
.env.test
파일은 테스트 환경 시 사용합니다. 만약, .env.test.local
이 있다면, .env.test
을 덮어쓴다.
$ npm run test$ yarn test
npm run test시 .env 파일도 실행되는 우선순위가 있다. 우선순위는 아래와 같다.
.env.test.local
> .env.test
> .env.local
> .env
리액트에서 .env 환경 설정 시 변수명에 REACT_APP_
이라고 앞에 붙여줘야 인식을 합니다. 만약 붙이지 않으면 무시합니다.
.env.*
와 같은 형식으로 환경 변수를 설정하는 방식은 React와 동일하고 우선 순위 또한 동일하게 동작합니다.
하지만 브라우저에서 환경 변수를 사용할 때, 환경 변수 앞에 붙는 prefix가 다른데 React는 REACT_APP_
, Next는 NEXT_PUBLIC_
을 붙여줘야 정상적으로 환경 변수를 인식합니다.
기본적으로 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 파일의 속성은 여기서 확인할 수 있습니다.
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} 앱이 서버에서 실행 중인지 여부React, Next, Vite 모두 환경 변수는 정적으로 참조되어야만 합니다.
예를 들어 import.meta.env[key]
와 같은 형식은 동작하지 않습니다.
환경 변수는 로컬 서버가 변경을 감지하지 못해 HMR 적용 대상이 아닙니다. 따라서 개발 서버(로컬 서버)가 구동 되는 상황에서 변경이 되었다면 개발 서버를 재시작 해야합니다.
환경 변수의 우선 순위는 다음과 같습니다.
환경 변수의 우선 순위는 다음과 같습니다.
환경 변수의 우선 순위는 다음과 같습니다.
너무 유익합니다 :)