安裝套件前，先擋下不相容的 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，檢查和快速入門都命名相同的最低值。
• 一個無依賴的測試涵蓋邊界和錯誤格式輸入。

這是獨立撰寫的範例，不代表曾測試第三方儲存庫。程式碼及文中結論均在 AI 輔助起草後經過人工覆核。