GitHub빌드 실패: 환경 변수 오류 해결

1. 문제 발생

빌드 시 두 가지 에러가 발생했다.

첫 번째 에러

Error: @supabase/ssr: Your project's URL and API key are required to create a Supabase client!

Check your Supabase project's API settings to find these values

이 에러는 Supabase 클라이언트를 초기화하는 데 필요한 프로젝트 URL과 API 키가 누락되었음을 나타낸다.

두 번째 에러

Error occurred prerendering page "/challenges/post". Read more: https://nextjs.org/docs/messages/prerender-error

Error: @supabase/ssr: Your project's URL and API key are required to create a Supabase client!

Check your Supabase project's API settings to find these values

이 에러는 Supabase 클라이언트를 SSR 중에 잘못 초기화하여 발생한 문제였다. 실제 문제의 핵심은 두 번째 에러로, 클라이언트 전용 코드가 SSR 과정에서 실행되면서 발생했다.

2. 원인 추론 및 해결 과정

2.1 첫 번째 에러 해결 과정

1) GitHub 환경 변수 설정 확인

Supabase 클라이언트를 초기화하려면 프로젝트의 URL과 API 키가 필요하다. 이를 GitHub Secrets에 NEXT_PUBLIC_SUPABASE_URL과 NEXT_PUBLIC_SUPABASE_ANON_KEY로 추가했다.

그러나 여전히 동일한 오류가 발생했다.

2) build_test 환경 변수 추가 및 설정 (실패) → 원래대로 복원

CI/CD 환경에서 환경 변수를 설정하는 방법을 시도했다.

(1) build_test에서 환경 변수 추가

- name: Build
  run: pnpm build
  env:
    NEXT_PUBLIC_SUPABASE_URL: ${{ secrets.NEXT_PUBLIC_SUPABASE_URL }}
    NEXT_PUBLIC_SUPABASE_ANON_KEY: ${{ secrets.NEXT_PUBLIC_SUPABASE_ANON_KEY }}

(2) next.config.js 파일 수정

/** @type {import('next').NextConfig} */
const nextConfig = {
  env: {
    NEXT_PUBLIC_SUPABASE_URL: process.env.NEXT_PUBLIC_SUPABASE_URL,
    NEXT_PUBLIC_SUPABASE_ANON_KEY: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY
  }
};

module.exports = nextConfig;

그러나 여전히 오류가 발생했고, 빌드 오류가 발생하지 않았던 과거 상황과 비교했을 때 원인이 아님을 확인하고 모든 설정을 원래대로 복원했다.

2.2 두 번째 에러 해결 과정

이 문제는 SSR 과정에서 클라이언트 전용 코드가 실행되는 것이 원인이었다.

1) dynamic을 사용하여 ssr: false 적용

import dynamic from 'next/dynamic';

const ChallengePostSelector = dynamic(() => import('@/components/features/challenges/post/challenge-post-selector'), {
  ssr: false
});

위 방식으로 클라이언트에서만 해당 컴포넌트가 로드되도록 수정했다.

2) useEffect와 useState 활용하여 클라이언트 여부 확인

const [isClient, setIsClient] = useState(false);

useEffect(() => {
  setIsClient(true);
}, []);

if (!isClient) return null;

3) typeof window !== 'undefined' 조건 추가

if (typeof window !== 'undefined') {
  // 클라이언트에서만 실행
}

2.3 추가 문제 발생 (성능 저하)

이러한 수정 후 빌드는 통과했지만, 로딩 속도가 현저히 느려지고 페이지 새로고침 시 버벅임이 발생했다.
이는 useState와 useEffect를 통해 클라이언트 여부를 확인하는 방식이 전체 페이지 렌더링을 지연시키기 때문이었다.

또한, 모든 코드에 일괄적으로 적용했기 때문에 불필요한 부분까지 SSR을 비활성화한 것이 원인이었다.

해결 방향:

• 정말 SSR이 필요 없는 부분에만 ssr: false를 적용
• 불필요한 클라이언트 측 렌더링 최소화

3. 환경 변수 문제 해결 (최종 원인 발견)

팀원의 의견을 참고하여 환경 변수 문제를 다시 확인했다.

3.1 GitHub 환경 변수 설정 문제

일단 내가 사용한 variables가 아니라 repository secrets에 설정해야 했다.

variables	repository secrets

또한 console.log를 통해 확인해 본 결과, SUPABASE_ANON_KEY와 SUPABASE_URL 값이 undefined로 출력이 되었다.

'use client';
import { SUPABASE_ANON_KEY, SUPABASE_URL } from '@/constants/env.constant';

console.log(SUPABASE_ANON_KEY, SUPABASE_URL); // undefined

3.2 build_test 환경 변수 추가 및 설정

- name: setting env
  run: |
    echo "NEXT_PUBLIC_SUPABASE_URL=${{ secrets.NEXT_PUBLIC_SUPABASE_URL }}" >> .env
    echo "NEXT_PUBLIC_SUPABASE_ANON_KEY=${{ secrets.NEXT_PUBLIC_SUPABASE_ANON_KEY }}" >> .env

- name: Build
  run: pnpm build

이 상태에서 빌드를 다시 진행한 후, console.log로 확인하니 환경 변수가 정상적으로 출력됨을 확인했다.

또한 환경 변수 문제를 해결한 후, prerendering 관련 임시 해결책을 모두 삭제해도 정상적으로 빌드 성공하였다.

4. 결론

초기 빌드 실패 원인

• GitHub Actions 빌드 환경에서 Supabase 환경 변수가 올바르게 전달되지 않음
• SSR 과정에서 환경 변수가 없으므로 Supabase 클라이언트 생성 시 에러 발생.

임시 해결책의 한계

• dynamic(ssr: false) 및 useEffect를 사용하여 SSR을 우회했지만, 이는 환경 변수 문제를 숨긴 것뿐이었음.
• 클라이언트 측에서만 실행되면서 로딩 속도 저하 및 버벅임 발생.

근본적인 해결책

• GitHub Actions에서 환경 변수를 올바르게 설정 (repository secrets 활용)
• prerendering 관련 임시 해결책 제거 후에도 정상 빌드 확인

SSR 관련 문제는 사실 환경 변수 설정 오류에서 비롯된 것이었고, 올바른 환경 변수 설정을 적용하자 SSR 우회 없이도 정상적으로 빌드가 가능했다. + 성능 저하도 없다.