프로젝트에서 Node.js 버전 명시 및 강제하기 - All About

package.json 파일의 engines 필드를 사용하면 해당 프로젝트가 작동하는 데 필요한 Node.js 버전을 명시할 수 있다. 단순히 기록용으로 남기는 것이 아니라, 협업 시 개발자들끼리 환경을 맞추거나 배포 환경(Vercel, Heroku 등)에서 특정 버전을 사용하도록 강제할 때 아주 유용하다.

설정 방법

package.json 파일에 아래와 같이 engines 항목을 추가한다.

{
  "name": "my-project",
  "version": "1.0.0",
  "engines": {
    "node": ">=18.0.0 <21.0.0"
  }
}

버전 범위 지정 (SemVer)

버전은 유연하게 지정할 수 있다.

• "node": "18.16.0": 정확히 이 버전만 허용
• "node": ">=18.0.0": 18버전 이상이면 모두 허용
• "node": "^18.0.0": 18.x.x 대의 최신 버전 허용

실제로 버전을 강제하는 방법 (중요!)

사실 package.json에 적어두기만 한다고 해서, 다른 버전을 쓴다고 실행이 막히지는 않는다. 진짜로 버전을 강제하고 싶다면 두 가지 방법이 있다.

• mise 를 사용하는 경우에는 mise use node@24.14.1 를 실행하면, mise.toml파일이 생성된다.
• .npmrc 파일 활용 (npm/pnpm) 프로젝트 루트에 .npmrc 파일을 만들고 아래 설정을 넣으면, 버전이 맞지 않을 때 설치(npm install) 자체가 중단됩니다.

  engine-strict=true
  

• nvm과 함께 사용 많은 개발자들이 .nvmrc 파일을 프로젝트 루트에 함께 둔다.
  • 파일 내용: v18.16.0
  • 이렇게 해두면 터미널에서 nvm use 한 번으로 package.json에 적힌 의도와 맞는 버전을 바로 맞출 수 있어 편리하다.

요약

"기록은 engines 필드에, 강제는 .npmrc 설정으로!" 라고 기억하면 된다.