제 컴퓨터에서는 되는데요? #1.빌드 과정 중 특정 모듈을 찾을 수 없음

들어가며

로컬에서 문제없이 동작하던 코드가 리모트 환경에서는 예기치 않게 실패하여 당황하신 적이 있으신가요? 최근 GitHub Actions에서 로컬 빌드와 배포 환경 간의 차이로 발생한 문제를 해결하며 배운 내용을 공유합니다.

문제 상황

로컬 환경에서는 Vite 빌드 시 정상적으로 완료되었지만, GitHub Action에서는 특정 모듈을 찾을 수 없다는 에러가 발생했습니다.

에러: 빌드 과정 중 XX 모듈을 찾을 수 없음

이 문제는 빌드 중 동적으로 생성되는 파일과 관련된 것으로 보였습니다. 분명 로컬에서는 동적으로 생성되는 파일을 잘 import 해오고 있는데, 왜 GitHub Actions에서만 문제가 발생한 걸까요?

디버깅

1. 에러 로그 분석

   • 로그에 따르면 빌드 중 특정 파일을 찾을 수 없다는 내용이 포함되어 있었습니다.
   • 해당 파일들은 로컬 환경에서는 정상적으로 생성되었지만, CI/CD 환경에서는 생성되지 않았습니다.

2. 파일 생성 과정 이해

   • 해당 파일들은 빌드 과정에서 특정 스크립트를 통해 동적으로 생성됩니다.
   • 이러한 파일들은 git의 관리 대상에서 제외(.gitignore)되어 있으며, 빌드 환경에 따라 생성됩니다. 즉, 로컬에서 push 하는 파일이 아닙니다.

   이 시점에서, 스크립트 실행 중 문제가 발생했을 가능성을 확인했습니다.

3. 파일 경로 문제 파악

   파일 생성 스크립트를 확인하여 아래와 같은 내용을 파악했습니다.

   • 스크립트 입력값으로 제공된 파일 경로와 실제 파일 이름 사이에 대소문자 차이가 있었습니다.
   • 예를 들어, 스크립트는 fileName.js라는 경로를 사용했지만, 실제 파일 이름은 filename.js였습니다.

   분명 다른 이름의 파일인데 로컬에서는 어떻게 문제없이 이 파일을 찾아서 import 할 수 있었을까요?

4. 운영체제별 파일 경로 대소문자 처리 차이

   문제의 핵심은 운영체제 간 파일 경로 처리 방식의 차이에 있었습니다:

   • 로컬 환경(macOS/Windows):
     • 이 운영체제들은 기본적으로 파일 경로를 처리할 때 대소문자를 구분하지 않습니다. 따라서 FileName.js와 filename.js를 동일한 파일로 간주합니다.
   • CI/CD 환경(Linux):
     • Linux는 대소문자를 구분합니다. 따라서 FileName.js와 filename.js를 서로 다른 파일로 간주해 에러가 발생했습니다.

   이 차이로 인해 로컬 환경에서는 문제가 없었지만, CI/CD 파이프라인에서는 실패한 원인을 확인할 수 있었습니다.

해결 방법

• 파일 생성 스크립트에서 수정해 파일명의 대소문자를 구분하고, 실제 파일명과 정확히 일치하도록 변경했습니다.
• 또한, 스크립트 실행 중에 발생한 에러가 감춰지는 문제를 해결하기 위해, 에러 발생 시 빌드를 중단하고 예외를 던지도록 개선했습니다. 이를 통해 디버깅 시간을 줄이고 문제를 빠르게 파악할 수 있었습니다.

나가며

이번 디버깅 경험을 통해 운영체제 간의 작은 차이도 빌드 실패를 유발할 수 있다는 것을 알게 되었습니다. 이러한 문제를 방지하기 위해 워크플로우를 설계할 때 운영체제별 차이를 고려하고, 에러를 신속히 감지할 수 있는 핸들링이 필요합니다.