배포 후 빌드 로그를 제대로 읽는 법

배포 자동화 도구에서 build 실패 메시지를 받으면 보통 화면을 휘리릭 지나간다. 하지만 그 로그에 문제의 원인이 명확하게 적혀 있는 경우가 많다. 몇 가지 포인트만 알면 build 로그에서 빠르게 원인을 찾을 수 있다.

핵심은 build 로그를 전체적으로 '읽는 것'이 아니라, 의미 있는 부분만 '찾는 것'이다.

Build 로그의 처음 부분

build 시작할 때 환경 변수, Node.js 버전, 패키지 매니저 버전 같은 메타정보가 있다. 이 부분이 예상과 다르면 배포 환경 설정이 잘못된 것이다.

> npm run build
Node version: v18.16.0
Npm version: 9.6.4
ENVIRONMENT: production
DATABASE_URL: <set>

Warning과 Error 구분

Warning은 무시할 수 있는 경우가 많지만, Error는 반드시 처리해야 한다. build 결과를 보면 warning과 error의 개수가 명확하게 나온다.

3 warnings
1 error

Build 로그의 마지막 부분

build 성공 또는 실패 메시지는 항상 로그의 마지막에 있다. 여기서 전체 결과와 어느 단계에서 실패했는지 알 수 있다.

# 성공
Build completed successfully

# 실패
Build failed: TypeScript compilation error
Build failed: Node module not found

TypeScript 에러

TypeScript 컴파일 에러가 있으면 파일 경로와 줄 번호, 에러 메시지가 출력된다.

src/pages/api/user.ts:42:5 - error TS2322: Type 'string' is not assignable to type 'number'.

이 메시지로 정확히 어느 파일의 몇 번 줄에 뭐가 문제인지 알 수 있다.

의존성 문제

node_modules에 필요한 패키지가 없거나 버전이 맞지 않으면 에러가 난다.

Cannot find module 'express'
Dependency "next" not installed

이 경우 npm install을 다시 하거나, package.json과 배포 환경의 npm 버전을 맞춰야 한다.

환경변수 관련 에러

Required 환경변수가 없으면 application이 시작조차 안 될 수 있다.

Error: DATABASE_URL is required
Error: API_KEY is not defined

build 시점에 필수 환경변수를 검증하는 코드가 있으면, 배포 후에 서버가 crash 되는 상황을 미리 방지할 수 있다.

Port나 파일 접근 에러

포트가 이미 사용 중이거나, 파일에 쓸 권한이 없으면 서버 시작 단계에서 에러가 난다.

Error: listen EADDRINUSE: address already in use :::3000
Error: EACCES: permission denied, open '/app/data/file.txt'

로그 저장

build 로그를 파일로 저장하면, 나중에 같은 에러가 나올 때 비교할 수 있다.

npm run build 2>&1 | tee build-$(date +%Y%m%d-%H%M%S).log

1. build 로그의 시작 부분에서 환경 정보를 확인한다.
2. 마지막 부분에서 success/error 메시지를 본다.
3. error가 있으면 파일 경로와 줄 번호를 따라 코드를 본다.
4. 환경변수나 의존성 문제가 있으면 배포 환경 설정을 확인한다.

마지막 확인

build가 성공한 후에도 실제 서버가 시작되는지 확인해야 한다. build가 성공했어도 서버가 시작 중에 crash 되면 의미가 없다. build 로그와 runtime 로그를 함께 보면서 어느 단계에서 문제가 생기는지 파악하는 게 중요하다.