Next.js Standalone 빌드 환경에서 pino-pretty 로그 출력 트러블슈팅: pnpm, transport, outputFileTracingIncludes 분석

핵심 기술

이 글은 Next.js의 standalone 빌드 환경에서 pino와 pino-pretty 라이브러리를 사용하여 서버 측 로그를 올바르게 출력하기 위한 트러블슈팅 과정을 상세히 다룹니다. pnpm의 심볼릭 링크 특성, pino의 transport 옵션, 그리고 Next.js의 outputFileTracingIncludes 설정이 문제 해결의 핵심 요소입니다.

기술적 세부사항

• 문제 정의: Next.js standalone 빌드 환경에서 pino-pretty를 transport 옵션으로 설정 시 unable to determine transport target for "pino-pretty" 오류 발생.
• 로깅 라이브러리 선정: Node.js 진영에서 많이 사용되는 pino와 pino-pretty 라이브러리 사용 결정.
• 초기 설정 시도: pino-pretty를 dependencies로 이동, import 구문으로 직접 가져오기 시도 등.
• pino-pretty의 CommonJS: pino-pretty가 CommonJS 형태로 작성되어 있어 target에 문자열 'pino-pretty'를 사용하는 것이 공식적으로 권장됨을 확인.
• Standalone 빌드의 동작 방식: Next.js standalone 빌드는 프로덕션 배포에 필요한 최소한의 파일만 복사하며, 사용하지 않는 모듈은 트리쉐이킹되어 포함되지 않음.
• outputFileTracingIncludes 활용: .next/standalone/node_modules에 pino-pretty 모듈이 누락되어 발생하는 문제를 해결하기 위해 outputFileTracingIncludes 설정을 통해 명시적으로 포함.
• 종속성 문제 발생: pino-pretty의 내부 종속성인 colorette 모듈을 찾지 못하는 uncaughtException 오류 발생.
• pnpm의 심볼릭 링크: pnpm은 패키지를 글로벌 store에 저장하고 심볼릭 링크로 연결하는 구조를 가지며, 이는 standalone 빌드 시 종속성 추적에 영향을 미침.
• node-linker=hoisted 설정: pnpm의 node-linker 설정을 hoisted로 변경하여 심볼릭 링크 대신 flat한 구조로 node_modules를 구성, 이를 통해 종속성 추적 문제를 해결.
• outputFileTracingIncludes 복잡성: hoisted 모드 사용 시 모든 하위 종속성을 명시적으로 outputFileTracingIncludes에 포함시켜야 하는 어려움.
• @vercel/nft와 정적 참조: Next.js standalone 빌드의 @vercel/nft 라이브러리가 import, require 구문의 '정적 참조'만 추적 가능하며, pino 내부의 모듈 해석 방식이 동적 참조로 작동하여 추적되지 않음을 분석.

개발 임팩트

이 트러블슈팅 과정을 통해 Next.js standalone 빌드 환경에서 발생할 수 있는 복잡한 로깅 문제를 해결하는 실질적인 방법을 습득할 수 있습니다. 또한, Node.js 모듈 시스템, pnpm의 패키지 관리 방식, Next.js 빌드 파이프라인에 대한 깊이 있는 이해를 얻게 되어 향후 유사한 문제 발생 시 효과적으로 대처할 수 있는 능력을 향상시킬 수 있습니다.

커뮤니티 반응

(본문에서 직접적으로 외부 커뮤니티 반응에 대한 언급은 없으나, 로깅 라이브러리 및 Next.js standalone 빌드 관련 이슈는 개발자 커뮤니티에서 자주 논의되는 주제입니다.)