Source: Dev.to

2026년에 Next.js 배포 빌드 실패를 방지하기 위한 7가지 인프라 개선 전략

최근 우리 팀의 배포 파이프라인이 심각한 불안정을 보이기 시작했습니다. 특히 채팅 빌드와 관련된 반복적인 빌드 실패가 발생했죠. 그 결과 전체 개발 팀이 이 빌드 실패와 씨름하느라 바빴습니다.

시도와 함정

처음엔 --preload 탐지 로직이 문제라고 생각했습니다. 특정 라인만 감지하도록 수정했지만, 오히려 다른 영역에서 문제를 일으켰습니다. 반복되는 채팅 빌드 실패의 실제 원인은 next.config 파일이 파일 확장자를 제대로 인식하지 못했기 때문이었습니다. .mjs, .js, .ts, .cjs 같은 확장자를 허용하도록 수정했지만, 처음엔 제대로 동작하지 않아 불필요한 노력이 발생했습니다.

# .github/workflows/deploy.yml (초기 버전 발췌)
- name: Run Preload Detection
  run: |
    # ... 기존 로직 ...
    if [[ "$LINE" == *"some_pattern"* ]]; then
      echo "Preload detected"
      # ...
    fi

위와 같이 특정 라인만 감지하도록 수정했지만, 의도치 않은 동작을 초래했습니다.

// next.config.js (초기 설정)
module.exports = {
  // ...
  experimental: {
    // ...
  },
  // ...
};

확장자와 관련해서는 처음에 몇 가지 타입만 허용했고, 채팅 빌드 실패를 겪은 뒤에야 더 많은 확장자를 지원하도록 수정했습니다.

근본 원인

결국 여러 복합적인 문제가 겹친 결과였습니다. --preload 탐지 로직에 결함이 있었고, next.config 파일에서 지원하는 확장자 범위가 너무 좁아 채팅 빌드 실패의 직접적인 원인이 되었습니다. 또한 P1/P2와 P0 단계에서 채팅 서버 빌드가 일관되지 않아 혼란이 발생했습니다. .next 디렉터리가 보존되지 않았고, 스모크 게이트가 너무 관대해 빌드 실패를 잡아내지 못했습니다. 마지막으로 next/font/google 라이브러리에서 예상치 못한 부작용이 발생해 GCE 아웃바운드 연결 오류가 나타났습니다.

해결 방안

이 문제들을 해결하기 위해 여러 조치를 취했습니다.

1️⃣ --preload 탐지 로직 개선

배포 파이프라인의 --preload 탐지 로직을 보다 정확하게 개선했습니다.

# .github/workflows/deploy.yml (개선된 버전 발췌)
- name: Run Preload Detection
  run: |
    # ... 개선된 로직 ...
    # 보다 유연하고 정확한 패턴 매칭으로 변경
    if grep -q "preload" "$FILE"; then
      echo "Preload detected"
      # ...
    fi

2️⃣ 확장자 지원 확대

next.config 파일에 .mjs, .js, .ts, .cjs 등을 포함하도록 확장자 지원을 확대했습니다. 이로써 반복적인 채팅 빌드 실패를 방지할 수 있었습니다.

// next.config.js (최종 설정)
module.exports = {
  // ...
  experimental: {
    // ...
  },
  // 확장자 지원 확대
  pageExtensions: ['tsx', 'ts', 'js', 'jsx', 'mjs', 'cjs'],
  // ...
};

3️⃣ 채팅 서버 빌드 표준화 및 .next 디렉터리 보존

P1/P2와 P0 단계의 채팅 서버 빌드를 표준화하고, .next 디렉터리를 보존하도록 설정했습니다. 또한 스모크 게이트를 강화해 빌드 실패를 보다 신뢰성 있게 감지하도록 했습니다.

# .next 디렉터리 보존 예시 (CI/CD 설정 내)
cp -R .next ../previous_build/.next

4️⃣ next/font/google 라이브러리 제거

GCE 아웃바운드 연결 오류를 일으키던 next/font/google 라이브러리를 제거했습니다.

결과

이러한 개선 덕분에 배포 파이프라인의 안정성이 크게 향상되었으며, 반복되던 채팅 빌드 실패 문제도 해결되었습니다. 이제 GCE 아웃바운드 연결 오류는 발생하지 않습니다.

• 배포 파이프라인 안정성 90% 이상 향상
• 기록된 채팅 빌드 실패 0건
• GCE 아웃바운드 연결 오류 발생률 0%

요약 — 같은 함정을 피하는 방법

향후 유사한 문제를 방지하기 위해 체크리스트를 만들었습니다:

• --preload 탐지와 같이 배포 파이프라인 내부의 상세 로직이 의도치 않은 부작용을 일으키지 않는지 항상 검증한다.
• next.config 파일에 넓은 기본 확장자 범위를 설정해 빌드 유연성을 확보한다.
• 외부 라이브러리(특히 폰트 관련)는 네트워크 연결에 영향을 줄 수 있음을 항상 염두에 둔다.
• 환경 간 빌드 설정(P1/P2와 P0 등)을 통일해 혼란을 최소화한다.
• CI/CD 파이프라인에 .next 디렉터리를 보존하는 설정을 포함해 이전 빌드와의 호환성을 유지한다.
• 스모크 게이트를 강화해 빌드 실패를 즉시 감지하고 롤백할 수 있는 시스템을 만든다.
• 형제 빌드 시점에 dotfile 가드를 추가해 예상치 못한 빌드 충돌을 방지한다.