🐛 [Bug] 빌드 환경에서 환경변수 process.env.NEXT_PUBLIC_API_URL이 undefined로 평가되는 문제 해결

[wynter24]

📄 문제상황

문제 #330

문제 원인

NEXT_PUBLIC_API_URL이 클라이언트에서는 잘 동작하지만, 서버 컴포넌트에서는 제대로 동작하지 않았습니다. 이는 환경 변수가 빌드 시점에 제대로 설정되지 않았기 때문입니다.

• Next.js는 빌드 시점에 process.env 값을 읽어 고정된 결과물을 생성합니다.
• CI/CD 워크플로우에서 환경 변수를 빌드 전에 전달하지 않아, 서버 컴포넌트에서 undefined 값을 참조하면서 에러가 발생했습니다.

✔️ 재현 가능 여부

• 예
• 아니오

💻 코드

문제 해결

GitHub Secrets를 사용하여 환경 변수를 CI/CD 환경에 전달하여 해결했습니다.

jobs:
  ci:
    steps:
    - name: Set environment variables
      run: echo "NEXT_PUBLIC_API_URL=${{ secrets.NEXT_PUBLIC_API_URL }}" >> .env
    - name: Build Next.js app
       env:
         NEXT_PUBLIC_API_URL: ${{ secrets.NEXT_PUBLIC_API_URL }}
       run: npm run build

문제 해결 과정

1. GitHub Secrets 등록

환경 변수를 안전하게 관리하기 위해 GitHub Secrets에 NEXT_PUBLIC_API_URL 값을 등록했습니다.

• 위치: 프로젝트 Repo > Settings > Secrets and variables > Actions
• 등록된 값은 GitHub Actions 워크플로우에서 참조할 수 있습니다.

2. 환경 변수 전달 설정

GitHub Actions 워크플로우에서 빌드 시점에 환경 변수를 전달하도록 설정했습니다.

1. 환경 변수 파일 생성

   GitHub Actions에서 Secrets 값을 가져와 CI/CD 환경에서 .env 파일을 생성하고 NEXT_PUBLIC_API_URL 값을 추가했습니다.

   - name: Set environment variables
     run: echo "NEXT_PUBLIC_API_URL=${{ secrets.NEXT_PUBLIC_API_URL }}" >> .env

   🔍이 .env 파일은 CI/CD 환경 내에서만 사용되며, 로컬의 .env와는 별개입니다. 빌드 및 서버 실행 시 환경 변수를 사용할 수 있도록 보장합니다.

2. 빌드 시 환경 변수 전달

   Next.js는 빌드 시점에 환경 변수를 읽어야 하기 때문에, 환경 변수를 명시적으로 전달했습니다.

   - name: Build Next.js app
     env:
       NEXT_PUBLIC_API_URL: ${{ secrets.NEXT_PUBLIC_API_URL }}
     run: npm run build

   🔍Next.js는 빌드 시점에 process.env 값을 고정된 값으로 읽기 때문에, 환경 변수를 빌드 단계에서 주입해야 올바른 결과물이 생성된다.

🙋🏻 참고 자료

🤔추가적으로 이해해야 할 점

• 빌드와 런타임의 차이
  • 빌드 시점: Next.js는 환경 변수를 읽어 정적 HTML과 JS를 생성합니다.
  • 런타임: 서버 실행 중에도 process.env에 접근 가능하지만, 빌드 시 환경 변수가 누락되면 런타임에서도 동작하지 않습니다.
• .env와 로컬 설정
  • CI/CD에서 생성된 .env 파일은 로컬의 .env와 별개입니다.
  • 로컬 환경에서는 .env.local 파일을 사용해 동일한 설정을 적용할 수 있습니다.

[wynter24]

문제 해결