[내보내번] Next.js docs - Environment Variables

내보내번(내가 보려고 내가 번역한...) Next.js docs

2021년 4월 3일 기준 Next.js 공식 문서를 번역했다.

※ 영어 전공자도 해외 유학파도 아니기에 번역에는 의역, 오역, 구글 번역이 무수히 많을 수 있으며, 혼자 공식문서를 참조해가며 번역하다 보니 오타도 많을 수 있다. 정확한 내용은 공식문서를 직접 살펴보거나 다른 정보들을 더 찾아보는 것을 추천한다.
(하지만 댓글 피드백도 환영합니다😃 )

Next.js 공식문서 확인하기>>

Basic Features: Environment Variables | Next.js

---

This document is for Next.js versions 9.4 and up. If you’re using an older version of Next.js, upgrade or refer to Environment Variables in next.config.js.

이 문서는 Next.js 9.4나 그 이상의 버전을 위한 것이다. 그 이전 버전의 Next.js를 사용하고 있다면 업그레이드하거나 Environmen Variables in next.config.js를 참조하라.

Next.js comes with built-in support for environment variables, which allows you to do the following:

• Use .env.local to load environment variables
• Expose environment variables to the browser

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

• 환경변수를 로드하기 위해 .env.local 사용
• 환경변수를 브라우저에 노출

Loading Environment Variables

Next.js has built-in support for loading environment variables from .env.local into process.env.
An example .env.local:

Next.js는 .env.local에서 process.env로 환경변수를 로딩하는 기본 지원을 제공한다. 
.env.local 예시:

This loads process.env.DB_HOST, process.env.DB_USER, and process.env.DB_PASS into the Node.js environment automatically allowing you to use them in Next.js data fetching methods and API routes.

process.env.DB_HOST, process.env.DB_USER와 process.env.DB_PASS를 Node.js 환경으로 자동으로 로드하여 Next.js data fetching methods와 API routes에서 환경변수들을 사용할 수 있다. 

For example, using getStaticProps:
예를 들면 getStaticProps 사용하는 것이다: 

Note: In order to keep server-only secrets safe, Next.js replaces process.env.* with the correct values at build time. This means that process.env is not a standard JavaScript object, so you’re not able to use object destructuring. Environment variables must be referenced as e.g. process.env.NEXT_PUBLIC_PUBLISHABLE_KEY, not const { NEXT_PUBLIC_PUBLISHABLE_KEY } = process.env.

노트: 서버 전용 비밀들을 안전하게 유지하기 위해서 Next.js는 process.env.*을 빌드 시간에 올바른 값으로 대체한다. 이 의미는 process.env가 JavaScript의 표준 객체가 아니라는 것이다. 따라서 객체 분해*가 불가능하다. 환경변수는 const { NEXT_PUBLISHABLE_KEY } = process.env가 아닌 process.env.NEXT_PUBLISHABLE_KEY와 같이 참조되어야 한다. 

*The destructuring assignment syntax is a JavaScript expression that makes it possible to unpack values from arrays, or properties from objects, into distinct variables.
*구조 분해 할당 구문은 배열이나 객체의 속성을 해체하여 그 값을 개별 변수에 담을 수 있게 하는 JavaScript 표현식입니다.
MDN Web Docs 참조>>

Note: Next.js will automatically expand variables ($VAR) inside of your .env* files. This allows you to reference other secrets, like so:
노트: Next.js는 .env*파일 안에 있는 변수($VAR)들을 자동으로 확장할 것이다. 자동 확장을 통해 다른 비밀들을 이와 같이 참조할 수 있다.

If you are trying to use a variable with a $ in the actual value, it needs to be escaped like so: \$.
실제 값에 $를 사용하고 싶다면, \$같이 처리해야 한다.

For example:

 

Exposing Environment Variables to the Browser

By default all environment variables loaded through .env.local are only available in the Node.js environment, meaning they won't be exposed to the browser.
기본으로 .env.local을 통해 로드된 모든 환경변수는 Node.js 환경에서만 사용할 수 있는데, 이 의미는 환경변수가 브라우저에는 노출되지 않는다는 것이다.

In order to expose a variable to the browser you have to prefix the variable with NEXT_PUBLIC_. For example:
브라우저에 변수를 노출시키기 위해서는 NEXT_PUBLIC_이라는 접두사를 사용해야 한다. 예를 들면:

This loads process.env.NEXT_PUBLIC_ANALYTICS_ID into the Node.js environment automatically, allowing you to use it anywhere in your code. The value will be inlined into JavaScript sent to the browser because of the NEXT_PUBLIC_ prefix. This inlining occurs at build time, so your various NEXT_PUBLIC_ envs need to be set when the project is built.
이렇게 하면 process.env.NEXT_PUBLIC_ANALYTICS_ID가 Node.js 환경에 자동으로 로드되고 코드 어디에서든 이 환경변수를 사용할 수 있다. 값은 NEXT_PUBLIC_ 접두사로 브라우저로 보내지는 JavaScript에 인라인 된다. 이 인라이닝은 빌드 시간에 일어남으로  환경변수들은 프로젝트가 빌드될 때 여러 NEXT_PUBLIC_ 환경을 설정해야한다. 

 

Default Environment Variables

In general only one .env.local file is needed. However, sometimes you might want to add some defaults for the development (next dev) or production (next start) environment.
보통 하나의 .env.local 파일만 필요하다. 하지만 때때로 개발 환경(next dev)이나 운영 환경(next start)을 위한 몇몇 기본 값들을 추가하고 싶을 수 있다. 

Next.js allows you to set defaults in .env (all environments), .env.development (development environment), and .env.production (production environment).
Next.js에서는 .env(모든 환경), .env.development(개발 환경), 그리고 .env.production(운영 환경)에 기본값들을 설정할 수 있다.

.env.local always overrides the defaults set.
.env.local은 항상 기본값을 오버라이드 한다. 

Note: .env, .env.development, and .env.production files should be included in your repository as they define defaults. 
.env*.local should be added to .gitignore, as those files are intended to be ignored. .env.local is where secrets can be stored.
노트: .env, .env.development, 그리고 .env.production 파일들은 기본값을 정의할 때 저장소에 포함되어 있어야한다. .env*.local은 무시되는 파일들로 .gitignore에 추가되어 있어야한다. .env.local은 비밀이 저장될 수 있는 곳이다. 

 

Environment Variables on Vercel

When deploying your Next.js application to Vercel, Environment Variables can be configured in the Project Settings.
Vercel에 Next.js 어플리케이션을 배포할 때에 환경변수는 프로젝트 설정에서 구성될 수 있다. 

All types of Environment Variables should be configured there. Even Environment Variables used in Development – which can be downloaded onto your local device afterwards.
모든 타입의 환경변수는 프로젝트 설정에서 구성되어야 한다. 개발 환경에서 사용된 환경변수도 이후에 로컬 기기에 다운로드할 수 있다.

If you've configured Development Environment Variables you can pull them into a .env.local for usage on your local machine using the following command:
개발 환경변수를 구성한 경우 로컬 머신에서 사용할 수 있도록 아래의 명령어를 통해 .env.local로 가져올 수 있다. 

When using the Vercel CLI to deploy make sure you add a .vercelignore that includes files that should not be uploaded, generally these are the same files included in .gitignore.
Vercel CLI을 사용하여 배포할 때 업로드되서는 안 되는 파일들을 포함하는 .vercelignore를 추가하였는지 확인하라. 대개 .vercelignore에 포함되어야 하는 파일들은 .gitignore의 파일들과 같다. 

 

Test Environment Variables

Apart from development and production environments, there is a 3rd option available: test. In the same way you can set defaults for development or production environments, you can do the same with .env.test file for testing environment (though this one is not so common as the previous two).
개발과 운영 환경 외에, 세 번째 옵션도 사용할 수 있다. 그 옵션은 테스트이다. 같은 방법으로 개발 혹은 운영 환경을 위한 기본값을 설정할 수 있고, 테스트 환경을 위해서 .env.test 파일에도 같은 방법으로 설정할 수 있다. (이 방법은 이전 두 방법처럼 보편적이지 않다.)

This one is useful when running tests with tools like jest or cypress where you need to set specific environment vars only for testing purposes. Test default values will be loaded if NODE_ENV is set to test, though you usually don't need to do this manually as testing tools will address it for you.
이것은 테스트 목적으로만 특정 환경변수를 설정해야 하는 jest 또는 cypress와 같은 테스팅 툴을 실행할 때 유용하다. 테스트 기본값은 NODE_ENV가 테스트로 설정되어 있으면 테스트 기본 값이 로드될 것인데 대개 테스팅 툴이 자동으로 처리해줄 것이기 때문에 수동으로 설정할 필요는 없다. 

There is a small difference between test environment, and both development and production that you need to bear in mind: .env.local won't be loaded, as you expect tests to produce the same results for everyone. This way every test execution will use same env defaults across different executions by ignoring your .env.local (which is intended to override the default set).
기억해둘 필요가 있는 테스트 환경과 개발, 운영 환경의 작은 차이점이 있다: .env.local은 모두에게 테스트 결과가 동일할 것으로 예상되어 로드되지 않을 것이다. 이러한 방법으로 모든 테스트 실행은 .env.local(기본 설정을 오버라이드 하기 위한 것)을 무시하여 여러 실행에서 동일한 env 기본값을 사용한다. 

Note: similar to Default Environment Variables, .env.test file should be included in your repository, but .env.test.local shouldn't, as .env*.local are intended to be ignored through .gitignore.
노트: 기본 환경 변수와 비슷하게, .env.test 파일은 저장소에 포함되어야 한다, 하지만 .env.test.local은 .env*.local이 .gitignore를 통해 무시되는 것처럼 저장소에 포함되서는 안 된다. 

While running unit tests you can make sure to load your environment variables the same way Next.js does by leveraging the loadEnvConfig function from the @next/env package.
단위 테스트를 실행하는 동안 @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)
}

 

느낀 점: 내가 보기 위해 글을 올리면서 개인적으로 좋은 점은 현재 Next.js로 프로젝트를 진행 중인데 구현할 때는 급하게 찾아서 사용했던 기능들의 의미나 용법들을 공식 문서를 통해 더 잘 알게 된다는 것이다. 어느 메소드, 속성을 사용하는 것이 더 좋은지 알게되고 잘못 사용하던 것을 발견해서 고치기도 하고 말이다. 새로운 기능을 알게 되는 것도 재밌다. 어제 누가 그냥 그때그때 공식 문서로 보면 되는데 굳이 왜 다 하나씩 번역하고 있냐는 말에 생각난 느낀 점을 적어본다.