광고 동기화 스크립트의 자동화 파이프라인 실패 원인 해결

site/package.json에서 sync-ads 스크립트가 --env-file-if-exists 옵션을 받도록 수정하고, CommonJS 대신 .mjs 포맷을 가리키도록 변경했다. 자동화된 게이팅 시스템에서 환경 파일이 항상 존재하는 것을 보장할 수 없던 상황에서 나온 실질적인 수정이다.

환경 파일의 존재 여부를 다루는 방식

일반적으로 로컬 개발 환경에서는 .env 파일이 프로젝트 루트에 존재한다. 개발자들이 설정 파일을 git ignore에 넣고 필요한 환경 변수를 로컬에서 관리하기 때문이다. 그런데 자동화 파이프라인에서는 상황이 다르다.

CI/CD 환경이나 autonomous gate(자동화된 게이팅 시스템)에서는:
- 환경 변수를 파일이 아닌 시스템 환경에서 주입하는 경우가 많다
- 보안상 민감한 설정은 파일로 배포하지 않는다
- 스크립트 실행 환경이 매번 새로 생성될 수 있다
- 격리된 컨테이너나 샌드박스에서 구동되기도 한다

이전에는 아마 스크립트가 .env 파일의 존재를 필수로 가정했을 것이다. 그러면 환경 파일이 없을 때 "파일을 찾을 수 없다"는 에러가 발생해서 전체 파이프라인이 실패했을 거다. 누군가 배포 로그를 들여다보면서 "왜 자동 파이프라인에서만 sync-ads가 실패하지?"라고 물어봤을 것 같다.

--env-file-if-exists 옵션을 추가하면 파일이 있으면 로드하고, 없으면 조용히 넘어간다:

훨씬 더 견고한 패턴이다. 개발 환경과 프로덕션 환경이 다른 만큼, 그 환경에 맞는 설정 방식을 지원하는 게 맞다.

CommonJS에서 ES Module로의 명시적 전환

.mjs 확장자는 Node.js가 이 파일을 ES Module로 명시적으로 인식하도록 한다.

{
  "scripts": {
    "sync-ads": "node --env-file-if-exists sync-ads.mjs"
  }
}

이렇게 가리키면 여러 이점이 생긴다:

1. 명시성: 파일명만 봐도 "이건 ES Module이다"를 알 수 있다
2. 호환성: 다른 도구들(번들러, 타입 체커, 린터)이 파일을 올바르게 해석할 가능성이 높아진다
3. 미래성: JavaScript 생태계가 점차 CommonJS에서 ES Module로 이동하는 흐름에 발 맞추기

특히 autonomous gate 같은 자동화 시스템에서는 여러 버전의 Node.js나 다양한 실행 환경을 거친다. 어쩌면 여러 프로젝트 스크립트가 한 번에 구동될 수도 있다. 그럴 때 파일 포맷을 명확히 하는 것만으로도 의외로 큰 안정성 향상이 된다. CommonJS와 ES Module이 섞여 있을 때 모듈 해석 에러가 발생할 수 있는데, 이런 식으로 확장자를 명시하면 그런 환경 차이 버그를 사전에 방지할 수 있다.

작은 변경, 큰 영향

이 수정은 package.json의 한두 줄 변경에 불과하다. 하지만 자동화 파이프라인의 안정성 관점에서는 꽤 중요한 수정이다.

팀 차원에서 본 효과:
- 배포 비용: 파이프라인 실패로 인한 재실행 줄임
- 인지 비용: "왜 자동화 게이팅에서만 실패하지?"라는 디버깅 시간 절감
- 환경 차이: 로컬과 자동화 환경의 격차를 줄임

이런 변경을 빨리 잡아내고 일반화하려면 몇 가지가 필요하다. 자동화 시스템에서 실제로 발생하는 에러를 팀과 공유하고, "왜 필요한가"를 스크립트 작성자에게 명확히 알려야 한다. 그래야 나중에 유사한 스크립트를 만들 때 이 패턴이 기본값이 될 수 있다. 결국 혼자서 "아, 이건 필수겠다"라고 판단하기보다는, 자동화 시스템이 표출한 실제 문제에서 비롯된 해결책이었다면 팀 전체가 같은 문제를 반복하지 않을 가능성이 훨씬 높다.

🛒 이 글과 어울리는 추천 상품

• 모니터 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 커피머신 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.