Node 버전 불일치가 왜 문제를 일으키나요?

로컬과 CI의 Node major 버전이 다르면 의존성 해석과 빌드 동작이 달라져 빌드 실패나 런타임 오류가 발생할 수 있습니다.

가장 안전한 해결 방법은 무엇인가요?

프로젝트에 .nvmrc 또는 engines를 명시하고 CI에서도 같은 버전을 고정해 재설치/재빌드하세요.

Choorai | 문서

CI/배포 환경 빈번 이슈

로컬에서는 되는데 CI에서만 실패하나요? Node.js 버전이 서로 다르면 빌드 결과가 달라질 수 있습니다.

TL;DR (핵심 요약)

1) 로컬/CI Node 버전 통일 2) .nvmrc 또는 engines 명시 3) 클린 설치 후 재빌드

주의

원인

현재 실행 중인 Node 버전이 패키지가 요구하는 최소/최대 버전 조건과 맞지 않습니다.

해결책

.nvmrc

package.json

{
  "engines": {
    "node": ">=20 <21"
  }
}

.github/workflows/ci.yml

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'

- run: npm ci
- run: npm run build

주의

lockfile이 오래되었거나 다른 Node 버전에서 생성된 경우, 버전을 맞춘 뒤 lockfile 재생성이 필요할 수 있습니다.

입력한 내용으로 새 이슈 페이지를 엽니다.