의존성 설치 전에 호환되지 않는 Node.js 버전 확인하기

패키지는 선언할 수 있습니다 "node": ">=20" 그리고 여전히 몇 명령어 후에 개발자에게 모호한 실패를 남깁니다. 런타임 버전을 실행 가능한 계약으로 다루세요: 명시하고, 확인하고, 의존성을 설치하기 전에 수리 지침과 함께 중지하세요.

작은 체크

의존성 없는 스크립트를 다음에 추가 scripts/check-node-version.mjs:

const requiredMajor = 20;
const actualMajor = Number.parseInt(process.versions.node.split(".")[0], 10);

if (!Number.isInteger(actualMajor) || actualMajor < requiredMajor) {
  console.error(
    `Node.js ${requiredMajor}+ is required; found ${process.versions.node}. ` +
    "Install an active LTS release, then rerun npm install."
  );
  process.exit(1);
}

console.log(`Node.js ${process.versions.node} satisfies the Node.js ${requiredMajor}+ requirement.`);

정상 설치 경로 전에 실행하십시오:

{
  "engines": { "node": ">=20" },
  "scripts": { "preinstall": "node scripts/check-node-version.mjs" }
}

그 engines 필드는 패키지 관리자와 호스팅 시스템이 요구 사항을 검사할 수 있게 합니다. 이 스크립트는 엔진 불일치에 대해서만 경고하는 패키지 관리자를 사용하는 사람에게도 동일한 요구 사항을 표시합니다.

문서가 동일한 정보 출처를 사용하게 하기

빠른 시작 가이드는 체크가 정확히 무엇을 강제하는지 말해야 합니다:

### Prerequisite

- Node.js 20 or newer (`node --version`)

If the install stops at the runtime check, install an active Node.js LTS
release and run `npm install` again.

“최근 Node.js 버전”과 같은 문구는 테스트할 수 없으며, 제품이 새로운 기준을 채택하는 즉시 이동합니다.

런타임을 변경하지 않고 두 브랜치를 테스트

비교를 순수 함수로 추출하여 회귀 테스트가 지원되는 버전과 지원되지 않는 버전을 모두 검증할 수 있도록 합니다:

export function supportsNode(version, requiredMajor = 20) {
  const major = Number.parseInt(version.split(".")[0], 10);
  return Number.isInteger(major) && major >= requiredMajor;
}

import assert from "node:assert/strict";
import { supportsNode } from "./supports-node.mjs";

assert.equal(supportsNode("18.20.8"), false);
assert.equal(supportsNode("20.0.0"), true);
assert.equal(supportsNode("22.19.0"), true);
assert.equal(supportsNode("not-a-version"), false);

이 검사는 의도적으로 범위를 좁게 설정했습니다. 일반 테스트 스위트는 여전히 최신 주요 릴리스 전반에서 호환성을 유지합니다. 이 검사는 선언된 최소값, 첫 번째 명령어, 빠른 시작이 서로 모순되지 않도록 유지합니다.

수용 체크리스트

• Node.js 18에서의 깨끗한 설치는 의존성 설치 전에 중지되고 필요한 버전을 명시함.
• Node.js 20에서의 깨끗한 설치는 패키지 관리자로 계속 진행됨.
• package.json, 체크 및 퀵스타트 모두 동일한 최소값을 명시합니다.
• 의존성 없는 테스트는 경계 및 잘못된 입력을 다룹니다.

이 독립적인 예시는 제3자 저장소에서 테스트했다고 주장하지 않습니다. 코드와 설명은 AI의 도움으로 초안을 작성한 뒤 사람이 직접 검토했습니다.