배포 파이프라인 회귀 3가지, printf와 distDir 격리로 해결!

배포 파이프라인에서 여러 회귀 문제가 발생해서 꽤 고생했어. 특히 빌드 과정에서 예상치 못한 에러들이 연달아 터지니까 정신이 하나도 없더라.

시도와 함정

처음에는 중첩된 heredoc 때문에 YAML 파싱 오류가 나는 걸 발견했어. 이걸 printf로 바꾸는 간단한 변경으로 해결될 줄 알았지.

# 이전 코드 (문제 발생)
cat <<EOF
key:
  nested_key: |
    $(some_command)
EOF

# 시도했던 코드 (printf 적용)
printf "key:\n  nested_key: |\n    %s\n" "$(some_command)"

그런데 이게 끝이 아니었어. 빌드 중에 .next 디렉토리가 없어서 500 에러가 나는 회귀도 있었고, RSC manifest 경로 때문에 또 다른 문제가 생기더라.

원인

중첩 heredoc은 쉘에서 파싱될 때 예상치 못한 방식으로 해석될 수 있어서 YAML 문법 오류를 일으키는 경우가 있었어. .next 디렉토리 부재는 빌드 과정에서 이 디렉토리가 제대로 생성되지 않거나, 이전 빌드 결과물이 남아있지 않아서 발생했지. RSC manifest 경로 문제는 Next.js의 빌드 아티팩트 관리 방식과 관련이 있었는데, 프론트엔드 빌드와 서버 빌드가 분리되면서 경로 참조에 문제가 생긴 거였어.

해결

먼저 중첩 heredoc은 printf를 사용해서 깔끔하게 처리했어.

printf "key:\n  nested_key: |\n    %s\n" "$(some_command)"

.next 디렉토리 문제는 distDir 설정을 격리하는 방식으로 해결했어. 이렇게 하면 각 빌드마다 독립적인 .next 디렉토리가 생성되어서 이전 빌드의 영향을 받지 않게 돼.

// next.config.js
module.exports = {
  experimental: {
    outputFileTracing: true,
  },
  distDir: '.next-build', // 각 빌드마다 고유한 디렉토리 사용
};

마지막으로 RSC manifest 경로 문제는 프론트엔드 빌드를 서버에서 직접 하도록 전환해서 해결했어. 이렇게 하면 빌드 환경이 통일되면서 경로 관련 문제가 줄어들더라고.

결과

• 배포 파이프라인의 YAML 파싱 오류가 완전히 사라졌어.
• 빌드 중 500 에러 발생 빈도가 크게 줄었어.
• RSC manifest 경로 관련 회귀 문제가 해결되어 안정성이 향상됐어.

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

• [ ] 배포 파이프라인에서 heredoc 사용 시, 쉘 해석 방식에 주의하고 printf로 대체하는 것을 고려하자.
• [ ] 빌드 시 .next 디렉토리와 같은 중간 결과물이 제대로 관리되는지 확인하고, distDir 격리 같은 방법을 검토하자.
• [ ] 프론트엔드와 서버 빌드 간의 의존성 및 경로 문제를 해결하기 위해 빌드 환경을 통일하는 방안을 고려하자.
• [ ] 각 단계별 회귀 가능성을 항상 염두에 두고, 문제 발생 시 원인 분석에 시간을 투자하자.