اكتشف نسخة 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، الفحص، والدليل السريع جميعها تسمي الحد الأدنى نفسه.
• اختبار خالٍ من التبعيات يغطي الحافة والمدخلات غير الصحيحة.

هذا مثال مستقل، ولا ندّعي أنه اختُبر على مستودع تابع لطرف آخر. راجعنا الشيفرة والادعاءات يدويًا بعد إعداد المسودة بمساعدة الذكاء الاصطناعي.