🐞 NestJS 증분 빌드 메커니즘 이해와 캐시 이슈 정리

1. 문제 상황

NestJS 프로젝트 개발 중 코드를 수정했음에도 불구하고 dist 폴더 내의 결과물이 갱신되지 않거나 심지어 dist 폴더 자체가 생성되지 않는 현상을 겪었다. nest start --watch 모드를 사용 중임에도 변경사항이 반영되지 않아 매번 수동으로 폴더를 지우고 다시 실행해야 하는 번거로움이 발생했다.

2. 원인 분석

이 문제의 핵심 원인은 TypeScript의 증분 빌드(Incremental Build) 메커니즘과 그 결과물인 tsconfig.tsbuildinfo 파일에 있었다.

증분 빌드란?
모든 파일을 매번 처음부터 컴파일하는 대신 마지막 빌드 이후 변경된 파일만 골라내어 컴파일함으로써 빌드 속도를 획기적으로 높여주는 기능이다.

TypeScript는 빌드 최적화를 위해 프로젝트의 구조와 의존성 그래프 정보를 tsconfig.tsbuildinfo 파일에 기록한다. 하지만 브랜치 전환, 수동 폴더 삭제 혹은 빌드 중 비정상 종료 등의 이유로 실제 파일 상태와 이 캐시 파일의 정보가 어긋나게 되면 컴파일러는 이미 모든 파일이 최신 상태라고 착각하여 빌드 과정을 건너뛰게 된다.

3. 해결 방법

방법 1 - 캐시 파일 강제 삭제
빌드 스크립트 실행 전 항상 캐시를 지우도록 package.json 을 수정하는 방법이다.

"script": {
  "prebuild": "rimraf dist tsconfig.tsbuildinfo",
  "build": "nest build",
  "start:dev": "nest start --watch"
}

OS에 상관없이 삭제 명령을 수행하기 위해 rimraf 패키지를 활용하였다.


방법 2 - NestJS CLI 설정 활용
nest-cli.json 설정을 통해 빌드 시마다 출력 경로(dist)를 자동으로 비우도록 설정하는 방법이다.

{
  "compilerOptions": {
    "deleteOutputPath": true
  }
}

방법 3 - 증분 빌드 비활성화
프로젝트 규모가 아직 크지 않아 빌드 속도 차이가 미미하다면 tsconfig.json 에서 이 기능을 아예 비활성화하여 변수를 차단할 수도 있다.

{
  "compilerOptions": {
    "incremental": false
  }
}

현재 진행 중인 프로젝트는 개인 프로젝트이고 초기 설계 단계라는 점을 고려하여 3번 방법(증분 빌드 비활성화)를 선택하였다.

초기 단계에서는 파일 구조 변경이나 리팩토링이 빈번하게 일어나므로 이때 빌드 속도를 몇 초 아끼는 것보다 캐시 꼬임으로 인해 발생하는 불필요한 디버깅 시간을 줄이는 것이 훨씬 생산적이라고 판단하였다.

추후 프로젝트 규모가 커져 컴파일 속도가 체감될 정도로 느려진다면 다시 증분 빌드를 도입하되 그때는 prebuild 스크립트를 통해 환경을 매번 초기화하는 방식을 병행하여 안정성을 확보할 계획이다.

더 빠른 빌드를 원한다면?
만약 증분 빌드를 끄면서도 속도를 놓치고 싶지 않다면 NestJS 9부터 공식 지원하는 SWC(Speedy Web Compiler) 도입을 고려할 수 있다. Rust 기반으로 tsc보다 훨씬 빠르면서도 캐시 관리 방식이 달라 위와 같은 문제를 겪을 확률이 줄어든다.