[Next.js] Environment Variables

next.js 공식문서를 읽고 정리해 놓은 문서입니다.
[참고] https://nextjs.org/docs/pages/building-your-application/configuring/environment-variables#loading-environment-variables

 

---

 

◼ 횐경변수 

• 서버 환경 변수 사용
  Next.js에서 서버 측에서 환경 변수를 사용할 때는 process.env를 사용하면 됩니다.
  NEXT_PUBLIC_ 접두사를 사용할 필요가 없습니다.
  

  // pages/api/hello.js
  export default function handler(req, res) {
    res.status(200).json({ message: process.env.SOME_SERVER_ENV_VAR });
  }
  서버 측에서는 process.env.VARIABLE_NAME으로 직접 환경 변수에 접근할 수 있습니다.

  
  
  
• 클라이언트 환경 변수 사용
  클라이언트 측에서 환경 변수를 사용하려면 NEXT_PUBLIC_ 접두사를 붙여야 합니다.
  const env = 'NEXT_PUBLIC_' 와 같이 변수로 사용하면 안됩니다.
  

  // pages/index.js
  export default function Home() {
    return (
      <div>
        <p>Client-side env: {process.env.NEXT_PUBLIC_SOME_CLIENT_ENV_VAR}</p>
      </div>
    );
  }
  클라이언트 측에서는 NEXT_PUBLIC_ 접두사를 붙인 환경 변수만 process.env.VARIABLE_NAME으로 접근할 수 있습니다.

  
  
  
• 환경 변수 접근
  process.env.VARIABLE_NAME과 같이 직접 접근해야 합니다.
  const env = process.env 와 같이 변수로 사용하면 안됩니다. 

// pages/api/hello.js
export default function handler(req, res) {
  res.status(200).json({ message: process.env.SOME_SERVER_ENV_VAR });
}
위 코드에서는 process.env.SOME_SERVER_ENV_VAR와 같이 환경 변수에 직접 접근하고 있습니다.

안되는 예시

// pages/index.js
export default function Home() {
  // ❌ 이렇게 하면 안됩니다.
  const env = process.env;

  return (
    <div>
      <p>Client-side env: {process.env.NEXT_PUBLIC_SOME_CLIENT_ENV_VAR}</p>
    </div>
  );
}

위 코드에서는 const env = process.env;와 같이 환경 변수를 변수에 할당하고 있습니다. 이렇게 하면 안됩니다. 대신 process.env.VARIABLE_NAME과 같이 직접 접근해야 합니다. 환경 변수는 process.env 객체를 통해 직접 접근해야 합니다. 변수에 할당하거나 다른 방식으로 사용하면 안됩니다. 이렇게 하면 환경 변수에 대한 접근이 명확해지고 코드의 가독성도 높아집니다.

 

 

 

요약하면, Next.js에서 환경 변수 사용 시 process.env와 NEXT_PUBLIC_ 접두사를 적절히 활용해야 하며, 변수로 간접 접근하는 것은 피해야 한니다.

 

 

 

---

 

 

 

 

◼ 규칙사항 

• $ 기호 사용 가능
  Next.js에서 환경 변수를 사용할 때 $ 기호를 변수명에 포함할 수 있습니다.
  예를 들어 $API_KEY와 같이 사용할 수 있습니다.
  

  // pages/api/hello.js
  export default function handler(req, res) {
    res.status(200).json({ message: process.env.$API_KEY });
  }
  Next.js에서는 환경 변수명에 $ 기호를 포함할 수 있습니다. 
  예를 들어 $API_KEY와 같이 사용할 수 있습니다.

  
  
  
• 숫자로 시작 불가
  변수명은 항상 문자로 시작해야 합니다.
  숫자로 시작하는 변수명은 사용할 수 없습니다.
  

  ❌ 잘못된 예:
  process.env.123_VARIABLE_NAME
  
  
  ✅ 올바른 예:
  process.env.MY_VARIABLE_123

  
  
  
  
• 특수문자 제한
  변수명에 사용할 수 있는 특수문자는 _(언더바)와 $(달러) 기호로 제한됩니다.
  그 외의 특수문자는 사용할 수 없습니다.
  

  ❌ 잘못된 예:
  process.env.MY_VARIABLE#
  process.env.MY@VARIABLE
  
  ✅ 올바른 예:
  process.env.MY_VARIABLE
  process.env.$MY_VARIABLE

  
  
  

 

 

---

 

 

 

 

◼ NODE_ENV 

• NODE_ENV의 허용 값
  production: 애플리케이션이 실제 운영 환경에서 실행되는 경우
  development: 개발 환경에서 애플리케이션이 실행되는 경우
  test: 테스트 환경에서 애플리케이션이 실행되는 경우
• 잘못된 예: 'staging'
  'staging'은 NODE_ENV의 허용 값이 아닙니다.
  일반적으로 'staging'은 운영 환경과 유사한 환경을 나타내기 위해 사용됩니다.
  하지만 Node.js에서는 'staging'을 공식적으로 지원하지 않습니다.
• 올바른 예: 'production', 'development', 'test'
  'production': 실제 운영 환경에서 애플리케이션이 실행되는 경우
  'development': 개발 환경에서 애플리케이션이 실행되는 경우
  'test': 테스트 환경에서 애플리케이션이 실행되는 경우

// 잘못된 예
process.env.NODE_ENV = 'staging'

// 올바른 예
process.env.NODE_ENV = 'production'
process.env.NODE_ENV = 'development'
process.env.NODE_ENV = 'test'

이렇게 NODE_ENV의 허용 값을 정확히 사용하는 것이 중요합니다.
이를 통해 애플리케이션의 동작 방식을 적절히 제어할 수 있습니다.
예를 들어, 운영 환경에서는 최적화된 코드를 사용하고, 개발 환경에서는 디버깅을 위한 추가 로깅을 활성화할 수 있습니다. 또한 테스트 환경에서는 특정 테스트 데이터를 사용할 수 있습니다.
따라서 NODE_ENV 값을 정확히 설정하는 것은 애플리케이션의 안정성과 성능을 높이는 데 중요한 역할을 합니다.

 

 

 

 

---

 

 

 

 

◼ TIP

• 변수 사용시 주의 사항
  변수 값에 $가 포함되어 있다면 이를 \$로 이스케이프 처리해야 합니다.
  

  //❌ 잘못된 예
  process.env.API_KEY = $ABCD1234
  
  //✅ 올바른 예
  process.env.API_KEY = \$ABCD1234

  
  
  
• 서버 시작 시 코드 실행
  register 함수를 사용하면 서버 시작 시 코드를 실행할 수 있습니다.
  

  // next.config.js
  module.exports = {
    async register(options) {
      console.log('Server is starting...');
    },
  };

  
  
  
• 런타임 구성 사용 자제
  runtimeConfig 옵션은 권장되지 않습니다. 대신 App Router를 점진적으로 도입하는 것이 좋습니다.
  

  // next.config.js
  module.exports = {
    // 권장되지 않음
    runtimeConfig: {
      apiKey: process.env.API_KEY,
    },
  };

  
  
  
• 환경 변수 파일 관리
  .env, .env.development, .env.production 파일은 리포지토리에 포함되어야 합니다. 이는 기본값을 정의하기 때문입니다.
  모든 .env 파일은 .gitignore에 의해 기본적으로 제외됩니다. 이를 통해 사용자가 이러한 값을 리포지토리에 커밋할지 여부를 선택할 수 있습니다.
  

  # .env
  API_KEY=$ABCD1234

  
  
  Vercel에 Next.js 애플리케이션을 배포할 때, .env* 파일의 환경 변수는 이름이 NEXT_PUBLIC_으로 시작하지 않는 한 Edge Runtime에 사용할 수 없습니다. 대신 Project Settings에서 환경 변수를 관리하는 것이 좋습니다.
  .env.test 파일은 리포지토리에 포함되어야 하지만, .env.test.local은 .gitignore에 의해 무시되어야 합니다. 이는 .env*.local 파일이 무시되도록 의도되었기 때문입니다.
  

  # .env
  API_KEY=$ABCD1234 # Edge Runtime에서 사용할 수 없음
  
  # .env
  NEXT_PUBLIC_API_KEY=$ABCD1234 # Edge Runtime에서 사용 가능