Clinic.js doctor 명령어로 HTML 리포트가 안 만들어질 때 해결 방법

Node.js 성능 진단 툴 Clinic.js의 clinic doctor를 쓰다 보면 Ctrl+C 눌렀는데 .html 파일이 안 생기는 경우가 꽤 많아요. 특히 최근 Node.js 버전(21.7 이상)에서 자주 발생합니다.

가장 자주 만나는 원인 Top 3 (2025~2026년 기준)

1. Node.js 21.7 이상 버전 호환성 문제 → process.once('beforeExit') 시그널 핸들링이 변경되어 보고서 생성이 안 됨 (GitHub 이슈 #480에서 확인됨)
2. 프로세스가 제대로 종료되지 않음 → SIGINT(SIGTERM) 처리 미완료, 또는 이벤트 루프가 멈추지 않음
3. 시각화 단계에서 실패 (데이터는 수집됐는데 HTML 빌드 실패)

실전에서 가장 잘 먹히는 해결 순서

방법 1 – 가장 추천 (90% 이상 해결됨)

# 1. 브라우저 자동 열기 끄고 실행
clinic doctor --no-open -- node app.js
# (또는 yarn start, npm run dev 등 평소 명령어)

# 2. 충분히 실행 후 Ctrl + C로 종료

# 3. 수동으로 HTML 생성
# .clinic 폴더 안에 있는 최신 폴더 이름을 확인 후 아래처럼 실행
clinic doctor --visualize-only .clinic/12345.clinic-doctor
# (12345는 실제 PID나 폴더명으로 바뀜)

→ 이렇게 하면 거의 확실하게 .html 파일이 생깁니다!

방법 2 – Node.js 버전 낮추기 (근본 해결)

 

# nvm 쓰는 경우 (추천)
nvm install 20
nvm use 20

# clinic 최신 버전으로 업데이트
npm install -g clinic@latest

# 다시 시도
clinic doctor --no-open -- node app.js

2026년 현재 Node 20 LTS가 가장 안정적이에요. Node 22나 23 쓰고 계시면 이 방법으로 대부분 해결됩니다.

방법 3 – 로그 자세히 보면서 디버깅

 

clinic doctor --no-open -- node --trace-warnings app.js 2>&1 | tee clinic-debug.log

→ clinic-debug.log 파일을 열어서 에러 확인 undefined만 나오거나 CSS 빌드 관련 에러가 보이면 → rm -rf node_modules 후 npm install 다시 해보세요 (의존성 꼬임)

한 줄 요약 치트시트

 

# 성공률 순서
clinic doctor --no-open -- node app.js     # → Ctrl+C → 
clinic doctor --visualize-only .clinic/xxxx.clinic-doctor

# 안 되면
nvm use 20 && clinic doctor --no-open -- node app.js

추가 팁

• .clinic 폴더가 이미 있으면 지우고 시작하세요 rm -rf .clinic
• 서버 환경(EC2, Docker 등)에서는 --collect-only → 로컬로 .clinic 옮겨서 --visualize-only
• Clinic.js는 Node.js 내부에 강하게 의존 → 최신 Node에서 자주 깨짐 → 가능하면 Node 20 LTS 고정 추천