2026년, Next.js 배포 빌드 실패 회귀 막는 7가지 Infra 개선 전략

2026년, Next.js 배포 빌드 실패 회귀 막는 7가지 Infra 개선 전략

얼마 전 우리 팀의 배포 파이프라인이 심각한 불안정성을 보이기 시작했어. 특히 chat 빌드 관련해서 빌드 실패가 계속 회귀하는 문제가 발생했지. 덕분에 개발팀 전체가 빌드 실패와 씨름하느라 정신이 없었어.

시도와 함정

처음에는 --preload 감지 로직이 문제라고 생각했어. 특정 줄만 감지하도록 수정했는데, 이게 오히려 다른 부분에서 문제를 일으키더라. chat 빌드 실패 회귀는 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: {
    // ...
  },
  // ...
};

확장자 관련해서도 처음에는 몇 가지 종류만 허용했다가, chat 빌드 실패를 겪고 나서야 더 많은 확장자를 지원하도록 수정했지.

원인

결국 여러 가지 복합적인 문제였어. --preload 감지 로직의 허점이 있었고, next.config 파일에서 지원하는 확장자 범위가 너무 좁았던 게 chat 빌드 실패의 직접적인 원인이었지. 또한, P1/P2 단계와 P0 단계의 chat 서버 빌드가 통일되지 않아 발생하는 혼란도 있었어. .next 디렉토리를 보존하지 않아 발생하는 문제도 있었고, smoke gate가 너무 허술했던 점도 빌드 실패를 잡아내지 못하는 원인이었지. 마지막으로 next/font/google 라이브러리가 GCE 아웃바운드 연결 오류를 유발하는 예상치 못한 부작용도 있었어.

해결

이 문제들을 해결하기 위해 여러 가지 조치를 취했어.

먼저, 배포 파이프라인의 --preload 감지 로직을 개선해서 더 정확하게 감지하도록 수정했지.

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

next.config 파일의 확장자 지원 범위를 .mjs, .js, .ts, .cjs까지 확장해서 chat 빌드 실패 회귀를 막았어.

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

P1/P2 및 P0 단계의 chat 서버 빌드를 통일했고, .next 디렉토리를 보존하도록 설정했어. smoke gate도 강화해서 빌드 실패를 더 확실하게 잡아내도록 만들었지.

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

마지막으로, next/font/google 라이브러리를 제거해서 GCE 아웃바운드 연결 오류를 차단했어.

결과

이러한 개선 작업 덕분에 배포 파이프라인의 안정성이 크게 향상되었고, chat 빌드 실패 회귀 문제가 해결되었어. GCE 아웃바운드 연결 오류도 더 이상 발생하지 않게 되었지.

• 배포 파이프라인 안정성 90% 이상 향상
• chat 빌드 실패 회귀 0건 기록
• GCE 아웃바운드 연결 오류 발생 빈도 0%

정리 — 같은 함정 안 빠지려면

앞으로 비슷한 문제를 겪지 않도록 몇 가지 체크리스트를 만들어 봤어.

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