Next.js 환경변수 설정, GitLab Runner 등록

Next.js 환경변수 설정

Next.js는 .env* 파일에서 환경 변수를 process.env로 로드하는 기능을 내장하고 있습니다.

• process : node.js에 내장된 전역 객체 (별도 import 필요 없음)
• process.env : node.js 환경에서 .env 파일과 같은 환경 변수 파일에 접근하기 위해 사용하는 자바스크립트 내장 객체

클라이언트용 환경 변수 번들링

Next.js는 빌드 시점에 NEXT_PUBLIC_ 접두사를 가지고 있는 환경 변수들을 js 번들에 인라인하여 클라이언트에 사용되는 모든 process.env.[variable] 참조를 하드코딩된 값으로 대체함

// 작업 전
await fetch(process.env.NEXT_PUBLIC_URL) 

// 작업 후 (빌드 완료)
await fetch('https://itpub.co.kr/') // 변수가 사라지고 값이 치환

서버용 환경 변수

NEXT_PUBLIC_ 접두사가 없는 경우 서버 사이드에서만 접근 가능, 클라이언트에서 접근 불가 즉 보안이 중요한 변수에 사용

node.js의 메모리에 상주하며, 서버 로직이 실행될 때만 process.env를 통해 동적으로 호출됩니다.

NEXT_DATABASE_URL=postgresql://...
NEXT_API_SECRET_KEY=xxx

환경 변수 우선 순위

개발 환경에서 실행 시 우선순위

1. .env.development.local
2. .env.local
3. .env.development
4. .env

프로덕션 환경에서 실행 시 우선순위

1. .env.production.local
2. .env.local
3. .env.production
4. .env

환경 변수 파일별 특징

1. env.local

• 가장 높은 우선순위의 로컬 오버라이드
• 로컬 환경에서만 사용되는 값
• git에 커밋되지 않아야 함 (보통 .gitignore에 포함)
• 개인적인 환경 설정이나 시크릿 키 저장에 적합

2. env.development

• 개발 환경(npm run dev)에서만 사용
• 팀원들과 공유해야 하는 개발 환경 설정

3 .env.production

• 프로덕션 환경(npm run build, npm run start)에서만 사용
• 실제 서비스에 필요한 환경 설정

4 .env.test

• 테스트 환경 전용
• .env.local 무시 (테스트 재현성)
• Vitest, Cypress 등 테스트 도구에서 사용

5 .env

• 모든 환경의 공통 기본값
• git에 커밋 가능
• 가장 낮은 우선순위

왜 Next.js는 env값을 자동으로 읽을 수 있는 걸까?

일반 node.js 프로젝트에선 dotenv라는 환경 변수를 로드할 수 있게 하는 라이브러리를 사용하는 게 일반적임. Next.js는 dotenv 라이브러리가 내장 되어있고 dotenv-expand 로직을 포함하고 있음

참고사항

• /src 디렉토리를 사용하는 경우, env 파일은 루트에 존재해야함
• NEXT_PUBLIC_ 변수는 빌드 시점의 값으로 고정, 런타임 환경 값을 액세스하려면 클라이언트에 값을 제공하기 위해 자체 API를 설정해야함
• 환경변수 NODE_ENV를 할당하지 않은 경우 next dev 명령 실행 시 Next.js에서 자동으로 NODE_ENV를 development로 설정, 이외 next build, next start 등에 명령 등에 대해선 production으로 설정함
  • 즉 쉽게 말해, 명령에 따라 Next.js가 똑똑하게 값을 자동으로 할당해준다는 것!

NODE_ENV란?

node.js 애플리케이션이 실행되는 환경(개발, 배포 등)을 정의하는 관습적인 환경 변수 주로 development와 production 모드를 구분하여 캐싱, 디버깅 도구 등 동작 방식을 조건부로 설정하는 데 사용

참고: NODE_ENV의 허용 값은 production, development, test

GitLab Runner

• GitLab Runner : 애플리케이션을 실행하여 파이프라인에서 GitLab CI/CD 작업을 수행하는 에이전트
• .gitlab-ci.yml 파일에 정의된 빌드, 테스트, 배포 및 기타 CI/CD 작업을 실행하는 역할을 담당

GitLab UI에 환경변수를 등록해야하는 이유

1. 보안성 강화 (Security & Compliance)

• DB 접속 정보, API Key 등 노출 시 위험한 정보를 소스코드(.env)에서 완전히 분리
• 코드 접근 권한과 별개로, Maintainer 이상의 관리자만 환경변수를 열람 / 수정할 수 있도록 제한하여 내부 보안 사고를 방지

2. 환경별 동적 주입 (Environment Scoping)

• 동일한 코드라도 Scope 기능을 통해 검증(QA), 운영(Prod) 환경에 맞는 변수를 자동으로 갈아 끼워 주입합니다.
• 수동으로 .env 파일을 옮기다 발생하는 설정 오류(Human Error)를 원천 차단합니다.

GitLab Runner CI CD 과정 요약

1. 변수 주입:
   파이프라인이 시작되면 GitLab 서버는 UI에 저장된 변수들을 Runner에게 전달, Runner는 이 변수들을 해당 배포 세션의 시스템 환경변수로 일시적으로 등록

2. 스크립트 실행:

• .gitlab-ci.yml에 적힌 npm run build 명령어가 실행될 때, Runner의 쉘(Shell) 환경에 등록한 변수들이 로드되어 있음. node.js는 실행될 때 이 시스템 환경변수들을 읽어 process.env 객체에 저장
• Next.js - NEXT_PUBLIC_ 변수는 코드 번들에 포함, 나머지는 서버 메모리에서 참조하도록 구성
• 빌드된 파일 중 정적파일은 Nginx(웹 서버)로, 서버 실행 파일은 Docker/AWS로 복사될 준비

3. 운영 서버 반영:
   Docker, AWS EC2 등 서버 컴퓨터 OS에 환경 변수로 설정되어 메모리에 적재

4. 서버 실행 및 런타임

• 클라이언트: 브라우저가 Nginx로부터 파일을 내려받음. 이미 값이 글자로 박혀 있으므로 서버와 상관없이 동작.
• 서버: npm start 시, Node.js 프로세스가 실행되면서 해당 서버 OS의 메모리(RAM)에 로드된 환경 변수를 실시간으로 호출하여 사용

GitLab CI/CD 환경변수 설정 가이드

1. GitLab UI에서 변수 등록하기
   가장 먼저 소스 코드에 담지 못하는 보안 값들을 GitLab 서버에 저장해야 합니다.

• 경로: Settings > CI/CD > Variables
• 방법: Add variable 클릭 후 Key(변수명)와 Value(값) 입력
• Environment scope 설정을 통해 development, qa, production 별로 동일한 변수명에 다른 값을 할당 가능 ex : API 요청 주소 NEXT_PUBLIC_URL

2. .gitlab-ci.yml 구성 (배포 스크립트)
   GitLab Runner가 빌드할 때 어떤 환경의 변수를 가져올지 지정

deploy_to_qa:
  stage: deploy
  script:
    - npm install
    - npm run build  # 이 시점에 GitLab에 등록된 QA용 NEXT_PUBLIC_ 변수들이 인라인됨
  environment:
    name: QA        # GitLab Variables의 Scope와 일치시켜야 함

트러블 슈팅

배포 환경에서 환경변수 로드 실패 (HTTP 500)

• 문제상황

  • 증상 : 로컬 환경에서는 Nodemailer를 통한 메일 전송이 정상 작동하나, GitLab CI/CD를 통해 배포된 QA 환경에서는 HTTP 500 Internal Server Error 발생.
  • 확인 : 브라우저 네트워크 탭 확인 결과, 서버(Next.js) 내부 로직 실행 중 에러 발생 확인.

• 문제원인 : GitLab CI/CD의 Protected Variable 설정 문제.

  • 원리: GitLab에서 변수를 등록할 때 Protected 옵션을 체크하면, 해당 변수는 'Protected Branches'(예: main)로 분류된 브랜치에서 실행되는 파이프라인에만 주입됨.
  • 결과: QA 브랜치에서 배포를 진행할 경우, Protected가 설정된 변수가 서버에 전달되지 않아 undefined 참조 에러 발생.

• 해결방법

  • GitLab Settings > CI/CD > Variables 메뉴 진입
  • 해당 변수의 Protected 옵션 체크 해제
  • 파이프라인 재실행을 통해 환경변수가 정상적으로 주입된 JS 번들 생성 및 배포

관련 참고 문서

GitLab 공식 문서 (Protected Variables)

참고 자료

Next.js 공식문서 - Environment Variables

Next.js의 환경 변수 파일 우선순위와 용도

Next.js 공식 블로그 (버전 9.4 릴리즈 노트) : 내장 로드 기능 처음 도입 되었을 때 작성 글

GitLab 공식 문서 (CI/CD Variables)

GitLab 공식 문서 (Environments)