package.json как договор: type, exports, диапазоны, lock

В прошлой статье всё решало расширение: .cjs — CommonJS, .mjs — ES-модуль при любых настройках проекта. Про обычный .js Node спрашивает package.json, причём не корневой, а ближайший: идёт от папки файла вверх и останавливается на первом найденном. "type": "module" в нём делает все .js ниже ES-модулями, "type": "commonjs" — модулями CommonJS. Главное здесь — остановка: package.json без поля type тоже прекращает поиск, и type из папки выше до файла уже не доходит.

На этом правиле держатся пакеты, которые везут две сборки сразу. У nodemailer 10.0.10 в корневом package.json стоит "type": "module", а в папке dist/cjs лежит свой package.json с единственным полем — { "type": "commonjs" }. Файлы в этой папке написаны через exports.x = …, и без такого файла не загрузились бы. Проверим на модели. Проект notes-api объявил "type": "module", в его node_modules лежат nodemailer и debug 4.4.3; у второго в package.json поля type нет вовсе. Прогноз: чем модель сочтёт сборку dist/cjs и главный файл debug, который лежит внутри проекта с "type": "module"?

// «диск» проекта: package.json — объектами, у файла с кодом — одна строка из него
const files = {
  "/app/package.json": { name: "notes-api", type: "module" },
  "/app/src/main.js": 'import nodemailer from "nodemailer";',
  "/app/src/legacy.cjs": 'const nodemailer = require("nodemailer");',
  "/app/node_modules/nodemailer/package.json": { name: "nodemailer", type: "module" },
  "/app/node_modules/nodemailer/dist/cjs/package.json": { type: "commonjs" },
  "/app/node_modules/nodemailer/dist/cjs/nodemailer.js": "exports.createTransport = createTransport;",
  "/app/node_modules/debug/package.json": { name: "debug", main: "./src/index.js" },
  "/app/node_modules/debug/src/index.js": "module.exports = require('./node.js');",
};

const dirname = (path) => path.slice(0, path.lastIndexOf("/")) || "/";

function moduleKind(path) {
  if (path.endsWith(".mjs")) return "ESM: расширение";
  if (path.endsWith(".cjs")) return "CommonJS: расширение";
  for (let dir = dirname(path); ; dir = dirname(dir)) {
    const pkgPath = (dir === "/" ? "" : dir) + "/package.json";
    const pkg = files[pkgPath];
    if (pkg) {
      if (pkg.type === "module") return "ESM: type в " + pkgPath;
      if (pkg.type === "commonjs") return "CommonJS: type в " + pkgPath;
      break;
    }
    if (dir === "/") break;
  }
  const esmSyntax = /^(import|export)\s/m.test(files[path]);
  return esmSyntax ? "ESM: type нет, в коде import или export" : "CommonJS: type нет, import и export не нашлись";
}

for (const path of Object.keys(files)) {
  if (!path.endsWith("/package.json")) console.log(path, "→", moduleKind(path));
}

Сборка dist/cjs стала CommonJS по своему package.json, хотя в корне пакета записано "type": "module": до корня поиск не дошёл. У debug поиск остановился на собственном package.json пакета. Поля type в нём нет, но это ближайший файл, и "type": "module" проекта на пакет не распространяется. Так и должно быть: пакет из node_modules написан под свой package.json, а не под настройки проекта, в который его поставили. Раз type не объявлен, решает сам текст файла: ни import, ни export в debug нет — значит, CommonJS.

Объявленный type — обещание, а не догадка. Файл с export под "type": "commonjs" Node заново не разбирает, а падает с SyntaxError: Unexpected token 'export'.

В модели определение по тексту упрощено до поиска строк, которые начинаются с import или export. Настоящий Node пробует разобрать файл как CommonJS и, если этому мешает синтаксис ES-модуля, разбирает его заново как ES-модуль. Проверим на своём проекте: package.json без type, в server.js — export. Прогноз: выполнится ли файл и скажет ли Node что-нибудь ещё?

{
  "name": "notes-api",
  "private": true
}

(node:<pid>) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file://<пример>/server.js is not specified and it doesn't parse as CommonJS.
Reparsing as ES module because module syntax was detected. This incurs a performance overhead.
To eliminate this warning, add "type": "module" to <пример>/package.json.
(Use `node --trace-warnings ...` to show where the warning was created)
слушаю порт 3000

Файл выполнился — слушаю порт 3000 стоит последней строкой. Но сначала Node предупредил: тип модуля не указан, разобрать файл как CommonJS не вышло, и его разобрали второй раз, уже как ES-модуль, — а это стоит времени. Подсказка называет и лечение — дописать "type": "module" в package.json. Предупреждение появляется, когда package.json есть, а type в нём нет; без package.json вовсе Node молча выполняет такой файл как ES-модуль. (node:<pid>) и <пример> — метки записи: номер процесса и полный путь у каждого свои.

Отсюда правило для своего проекта: type пишут всегда, даже когда всё и так работает. Дело не только в двойном разборе. Файл без import и export сегодня CommonJS, но стоит дописать в него строку с import, и он станет ES-модулем, а module.exports ниже упадёт с ReferenceError: module is not defined in ES module scope. С объявленным type вид файла не зависит от того, что в нём написано.

Вход в пакет в первой задаче статьи про require задавало поле main — одна строка, один файл для всех. У современного пакета рядом есть поле exports, и если оно есть, main Node не читает вовсе. exports делает две работы. Во-первых, это список дверей: подключить можно только перечисленные пути, а всё остальное закрыто, даже существующий файл. Во-вторых, у каждой двери бывают условия — объект, где ключ называет случай, а значение — файл для этого случая.

Случаи Node знает свои. Для import это набор node, node-addons, module-sync и import, для require — те же, но с require вместо import. Ключ default подходит всегда. Важно, как набор применяется: Node идёт по ключам объекта в том порядке, в каком они записаны в package.json, и берёт первый ключ из своего набора. Не самый точный и не самый специальный, а первый. Порядок внутри набора ничего не значит — решает порядок ключей у пакета.

Резолвер ниже разбирает настоящий exports пакета zod 4.6.5 — два входа из двенадцати. Первым ключом у каждого стоит @zod/source. Такого условия Node не знает — это своё условие zod, и Node его пропускает. Инструмент, которому это условие назвали (у node для этого есть флаг --conditions), получит исходник на TypeScript. Второй пакет, notes-kit, отдаёт две сборки, но ключ default у него записан первым. Прогноз: какой файл достанется import у notes-kit и что изменит @zod/source, дописанное в конец набора условий?

// exports настоящего zod 4.6.5, два входа из двенадцати
const zod = {
  name: "zod",
  exports: {
    ".": { "@zod/source": "./src/index.ts", types: "./index.d.cts", import: "./index.js", require: "./index.cjs" },
    "./mini": { "@zod/source": "./src/mini/index.ts", types: "./mini/index.d.cts", import: "./mini/index.js", require: "./mini/index.cjs" },
  },
};
// тот же приём с переставленными ключами
const notesKit = {
  name: "notes-kit",
  exports: { default: "./dist/index.cjs", import: "./dist/index.js" },
};

// условия, которые знает Node 26; default подходит всегда
const nodeImport = ["node", "node-addons", "module-sync", "import"];
const nodeRequire = ["node", "node-addons", "module-sync", "require"];

function pick(target, conditions) {
  if (typeof target === "string") return target;
  for (const [key, value] of Object.entries(target)) {
    if (key === "default" || conditions.includes(key)) {
      const found = pick(value, conditions);
      if (found !== undefined) return found;
    }
  }
  return undefined;
}

function resolveExports(pkg, subpath, conditions) {
  // строка или объект одних условий — сокращённая запись входа "."
  const short = typeof pkg.exports === "string" || !Object.keys(pkg.exports)[0].startsWith(".");
  const map = short ? { ".": pkg.exports } : pkg.exports;
  const target = Object.hasOwn(map, subpath) ? pick(map[subpath], conditions) : undefined;
  if (target === undefined) throw new Error(`${pkg.name}: путь ${subpath} не открыт через exports`);
  return target;
}

function show(label, pkg, subpath, conditions) {
  try {
    console.log(`${pkg.name} ${subpath} (${label}) →`, resolveExports(pkg, subpath, conditions));
  } catch (err) {
    console.log(err.message);
  }
}

show("import", zod, ".", nodeImport);
show("require", zod, ".", nodeRequire);
show("import + @zod/source", zod, "./mini", [...nodeImport, "@zod/source"]);
show("require", zod, "./index.cjs", nodeRequire);
show("import", notesKit, ".", nodeImport);

import и require получили у zod разные файлы, а types не сработал ни разу: такого условия в наборе Node нет. Вторым он стоит не случайно. TypeScript читает тот же exports со своим набором, где types есть, и тоже берёт первый подходящий ключ — окажись types после import, компилятор до него не дошёл бы. @zod/source победил, хотя в наборе стоял последним: у пакета этот ключ первый. Путь ./index.cjs в exports не перечислен, и дверь закрыта, хотя файл на месте.

А notes-kit отдал import CommonJS-сборку: default подходит всем и стоит первым, до ключа import очередь не дошла. Node такую запись принимает молча, и заметить ошибку можно только по тому, что ES-сборку не загружает никто. Поэтому default всегда ставят последним.

Теперь настоящий Node. Папку node_modules в записанный пример не положить, поэтому пакет подключает сам себя: если в package.json есть name и exports, файлы внутри проекта могут звать его по имени. main в примере указывает на ES-сборку, условие import — тоже на неё, require — на CommonJS-сборку. main.cjs подключает пакет обоими способами, пробует закрытый путь и сравнивает функции createNote из двух сборок. Прогноз: что получит require, чем кончится подключение notes-kit/src/index.cjs и совпадут ли функции?

{
  "name": "notes-kit",
  "type": "module",
  "main": "./src/index.js",
  "exports": {
    ".": {
      "import": "./src/index.js",
      "require": "./src/index.cjs"
    }
  }
}

require: CommonJS-сборка, src/index.cjs
notes-kit/src/index.cjs: ERR_PACKAGE_PATH_NOT_EXPORTED
import: ESM-сборка, src/index.js
одна и та же createNote: false

require получил CommonJS-сборку, хотя main указывает на ES-сборку: при поле exports Node на main не смотрит. Закрытый путь дал ERR_PACKAGE_PATH_NOT_EXPORTED, хотя файл src/index.cjs существует и строкой выше уже загружен через require("notes-kit"). Строка про import пришла позже: import() возвращает промис, и его then выполнился после синхронного кода.

Последняя строка — ловушка двух сборок. В одном процессе оказались два модуля с одним смыслом, и createNote в них — разные функции. С функциями это не страшно, с состоянием — страшно: кеш, счётчик, класс ошибки для instanceof у каждой сборки свои. Библиотека, которую ваш код подключает через import, а соседний пакет — через require, живёт в процессе дважды.

Пакеты обходят это тремя способами. pg 8.23.0 держит одну настоящую сборку на CommonJS, а файл для import у него — тонкая обёртка: import pg from '../lib/index.js' и повторный экспорт полей. @nestjs/common 12 публикует только ES-модули: "type": "module", вход "." в exports — строка "./index.js", и проект на CommonJS подключает его через require ES-модуля. Третий способ — условие module-sync. Node 26 проверяет его и для import, и для require, поэтому ES-сборка под этим ключом достаётся обоим, и копия одна. Одна оговорка: в такой сборке не должно быть await верхнего уровня — почему, объясняет следующий раздел.

Долгие годы require ES-модули не загружал, и пакет, ушедший на ESM, проекту на CommonJS доставался только через асинхронный import(). В Node 26 require загружает ES-модуль без флагов и предупреждений, и на этом держится переход Nest 12 на ESM. Условий два, и оба следуют из того, что вы уже знаете. require синхронный: он возвращает результат сразу, ждать ему некогда. Значит, в подключаемом графе ES-модулей не должно быть await на верхнем уровне — такой модуль не выполнить до конца, не отдав управление. И в графе не должно быть круга через require: недописанный exports CommonJS и строгий порядок выполнения ESM друг с другом не уживаются.

В примере main.cjs подключает три ES-модуля. format.mjs — обычный, с экспортом по умолчанию. config.mjs читает settings.json через await прямо на верхнем уровне. report.mjs сам импортирует main.cjs, который его подключает. Прогноз: какие ключи окажутся у объекта из format.mjs, какие из подключений упадут и где встанет строка с портом?

const format = require("./format.mjs");
console.log("format.mjs:", Object.keys(format).join(", "));
console.log(format.default("купить хлеб"));

try {
  require("./config.mjs");
} catch (err) {
  console.log("config.mjs:", err.code);
  console.log(err.message.split("\n")[0]);
}
import("./config.mjs").then((config) => console.log("import() config.mjs: порт", config.port));

try {
  require("./report.mjs");
} catch (err) {
  console.log("report.mjs:", err.code);
}

module.exports = { name: "notes-api" };

format.mjs: __esModule, default, prefix
заметка: купить хлеб
config.mjs: ERR_REQUIRE_ASYNC_MODULE
require() cannot be used on an ESM graph with top-level await. Use import() instead. To see where the top-level await comes from, use --experimental-print-required-tla.
report.mjs: ERR_REQUIRE_CYCLE_MODULE
import() config.mjs: порт 3000

require вернул объект пространства имён — такой же, какой дал бы import * as. Экспорт по умолчанию лежит в поле default, а не отдаётся целиком, как module.exports. Лишний ключ __esModule Node добавил, потому что у модуля есть экспорт по умолчанию, и ради этого ключа отдал обёртку над пространством имён: import() того же файла вернёт объект без него. По этой пометке код, который TypeScript или Babel собрали в CommonJS, понимает, что default надо брать из поля. Модуль без экспорта по умолчанию пометки не получает.

config.mjs упал с ERR_REQUIRE_ASYNC_MODULE, и текст ошибки сразу называет выход — import(). Он возвращает промис и потому может дождаться await внутри модуля: строка с портом пришла последней, после всего синхронного кода. report.mjs дал ERR_REQUIRE_CYCLE_MODULE. main.cjs ещё выполняется и свой module.exports не дописал, а ES-модулю нужен законченный модуль. Та самая половина, которую в статье про круг CommonJS отдавал без ошибки, здесь превращается в ошибку при загрузке.

require(esm) не обходит exports. Пакет, у которого в условиях есть только import, для require закрыт: Node ответит ERR_PACKAGE_PATH_NOT_EXPORTED раньше, чем дойдёт до загрузки модуля.

Как читаются ^ и ~, показала таблица в статье про npm: крышка разрешает всё до следующего мажора, тильда — до следующего минора. Две вещи в таблицу не поместились, а на сервере встречаются постоянно.

Первая — версии с нулём впереди. По соглашению semver 0.y.z — начальная разработка, и ломать в ней можно что угодно. Поэтому крышка не пускает дальше первой ненулевой цифры: ^0.2.3 — от 0.2.3 до 0.3.0, а ^0.0.3 — от 0.0.3 до 0.0.4, то есть одна версия. Пример рядом: у drizzle-orm под тегом latest на 29 сентября 2026 года стоит 0.45.3, а 1.0 выходит кандидатами. ^0.45.3 не притянет 0.46.0 — для пакета на нуле смена минора и есть смена мажора.

Вторая — предварительные версии: 8.0.0-rc.15, 1.0.0-rc.4, 3.0.0-canary.1. Дефис с суффиксом значит «ещё не выпуск», и такая версия младше выпуска с теми же тремя числами: 8.0.0-rc.15 идёт до 8.0.0. Суффикс сравнивается по частям между точками: числа — как числа, слова — по алфавиту, число младше слова. Главное правило: диапазон без дефиса предварительную версию не пропускает — ни ^7.10.0, ни >=7.0.0. Поэтому кандидат, который стоял у prisma на теге latest, в проект с диапазоном ^7.10.0 не приедет — только к тому, кто поставил пакет без версии. Тем же путём он придёт и по записи *: для неё npm и pnpm берут версию под тегом latest, не спрашивая semver. Если же диапазон сам назван предварительной версией, как ^8.0.0-rc.15, он пропустит следующие кандидаты того же выпуска и сам выпуск, но не предварительные версии других выпусков.

Соберём проверку. parse раскладывает версию на три числа и части суффикса, compare сравнивает две версии, satisfies строит для ^ и ~ верхнюю границу и отдельно проверяет суффикс. Прогноз: какие из семи проверок дадут true?

// "8.0.0-rc.15" → { release: [8, 0, 0], pre: ["rc", 15] }
function parse(version) {
  const [release, pre = ""] = version.split(/-(.*)/);
  return {
    release: release.split(".").map(Number),
    pre: pre === "" ? [] : pre.split(".").map((part) => (/^\d+$/.test(part) ? Number(part) : part)),
  };
}

function compare(a, b) {
  const x = parse(a);
  const y = parse(b);
  for (let i = 0; i < 3; i++) {
    if (x.release[i] !== y.release[i]) return x.release[i] - y.release[i];
  }
  // выпуск без суффикса старше любой своей предварительной версии
  if (x.pre.length === 0 || y.pre.length === 0) return y.pre.length - x.pre.length;
  for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
    const p = x.pre[i];
    const q = y.pre[i];
    if (p === q) continue;
    if (p === undefined) return -1;
    if (q === undefined) return 1;
    // числа сравниваются как числа и стоят раньше слов
    if (typeof p !== typeof q) return typeof p === "number" ? -1 : 1;
    return p < q ? -1 : 1;
  }
  return 0;
}

function satisfies(version, range) {
  const op = range[0] === "^" || range[0] === "~" ? range[0] : "";
  const base = range.slice(op.length);
  if (op === "") return compare(version, base) === 0;
  const [major, minor, patch] = parse(base).release;
  let upper;
  if (op === "~") upper = `${major}.${minor + 1}.0`;
  else if (major > 0) upper = `${major + 1}.0.0`;
  else if (minor > 0) upper = `0.${minor + 1}.0`;
  else upper = `0.0.${patch + 1}`;
  if (compare(version, base) < 0 || compare(version, upper) >= 0) return false;
  const v = parse(version);
  const b = parse(base);
  return v.pre.length === 0 || (b.pre.length > 0 && b.release.join(".") === v.release.join("."));
}

const checks = [
  ["0.2.9", "^0.2.3"],
  ["0.3.0", "^0.2.3"],
  ["0.0.4", "^0.0.3"],
  ["8.0.0-rc.15", "^7.10.0"],
  ["8.0.0", "^8.0.0-rc.15"],
  ["8.0.0-rc.16", "^8.0.0-rc.15"],
  ["8.1.0-beta.1", "^8.0.0-rc.15"],
];
for (const [version, range] of checks) {
  console.log(`${version} в ${range}:`, satisfies(version, range));
}
console.log(["8.0.0", "8.0.0-rc.10", "8.0.0-rc.2", "8.0.0-beta.3"].sort(compare).join(" < "));

Верхние границы вышли разные: у ^0.2.3 это 0.3.0, у ^0.0.3 — 0.0.4, поэтому 0.0.4 уже мимо. 8.0.0-rc.15 в ^7.10.0 не прошёл, и здесь пригодилась вторая проверка: границу 8.0.0 он формально не пересекает, ведь предварительная версия младше выпуска. Без отдельного запрета на суффикс кандидат восьмой версии пролез бы в диапазон седьмой. ^8.0.0-rc.15 пропустил rc.16 и выпуск 8.0.0, а 8.1.0-beta.1 — нет: это предварительная версия другого выпуска. В сортировке rc.2 встал раньше rc.10 — число сравнилось числом, а строкой было бы наоборот.

Результаты совпадают с пакетом semver, которым пользуется сам npm: модель сверена с semver 7.8.4 из npm 11.17.0 на всех парах из двух с лишним сотен версий с суффиксами и без, для ^, ~ и точной версии.

Диапазон в package.json — пожелание: «подойдёт любая 4.x не младше 4.3.4». Какую версию поставить, решает установщик, и решение зависит от дня: сегодня самая свежая подходящая одна, через неделю другая. Lock-файл записывает решение: точную версию каждого пакета, включая зависимости зависимостей, хеш архива и — это понадобится дальше — диапазон, из которого решение принято. Установка по lock-файлу не решает заново, а повторяет записанное.

Цену разницы показывает настоящая история. 8 сентября 2025 года после взлома учётной записи сопровождающего в реестре появилась debug 4.4.2 с вредоносным кодом, и в тот же день её сняли — как версии axios, которых нет в списке. Диапазон ^4.3.4 она проходила. Модель ниже ставит debug через полчаса после её выпуска: по lock-файлу, записанному в июне; без lock-файла; без lock-файла, но с запретом на версии моложе суток. Последняя попытка — CI, где диапазон в package.json подняли, а lock-файл не обновили. Прогноз: какие версии получатся в первых трёх строках и что ответит CI в четвёртой?

// parse, compare и satisfies из примера с диапазонами — в подложке
// debug в реестре через полчаса после выпуска 4.4.2: версия → время выпуска
const registry = {
  debug: {
    "4.3.4": "2022-03-17T13:38:47Z",
    "4.4.0": "2024-12-06T12:32:46Z",
    "4.4.1": "2025-05-13T20:56:36Z",
    "4.4.2": "2025-09-08T13:12:39Z",
  },
};
const now = Date.parse("2025-09-08T13:40:00Z");

function resolve(name, range, minAgeHours) {
  return Object.entries(registry[name])
    .filter(([version, published]) => satisfies(version, range) && now - Date.parse(published) >= minAgeHours * 3600_000)
    .map(([version]) => version)
    .sort(compare)
    .at(-1);
}

function install(pkg, lock, { frozen = false, minAgeHours = 0 } = {}) {
  const result = {};
  for (const [name, range] of Object.entries(pkg.dependencies)) {
    const locked = lock[name];
    if (locked?.specifier === range) {
      result[name] = locked;
    } else if (frozen) {
      throw new Error(`lock устарел: ${name} (lock: ${locked?.specifier ?? "нет"}, package.json: ${range})`);
    } else {
      result[name] = { specifier: range, version: resolve(name, range, minAgeHours) };
    }
  }
  return result;
}

const pkg = { dependencies: { debug: "^4.3.4" } };
// lock записан в июне
const lock = { debug: { specifier: "^4.3.4", version: "4.4.1" } };

console.log("CI по lock:", install(pkg, lock, { frozen: true }).debug.version);
console.log("без lock:", install(pkg, {}).debug.version);
console.log("без lock, версии не моложе суток:", install(pkg, {}, { minAgeHours: 24 }).debug.version);

const edited = { dependencies: { debug: "^4.4.0" } };
try {
  install(edited, lock, { frozen: true });
} catch (err) {
  console.log("CI после правки диапазона:", err.message);
}

По lock-файлу CI получил 4.4.1: решение принято в июне, и выход новой версии его не касается. Без lock-файла установщик честно взял самую свежую подходящую — 4.4.2. Запрет на версии моложе суток вернул 4.4.1, и в pnpm 11 такой запрет включён по умолчанию: настройка minimumReleaseAge равна 1440 минутам. Версия, которую сняли в день выхода, до такой установки просто не доживает.

А правка диапазона без переустановки обернулась ошибкой, и это не придирка. Lock-файл помнит, что 4.4.1 выбрана из ^4.3.4. Для ^4.4.0 выбора никто не делал, и сделать его молча в CI значило бы поставить на сервер то, что ни разу не ставилось у разработчика.

Теперь настоящий pnpm — менеджер, на котором собран монорепо учебника. В папке только package.json с двумя зависимостями. Флаг --offline велит брать пакеты из хранилища на диске и не ходить в сеть: так запись не зависит от того, что реестр отдаст в день съёмки. Вкладка pnpm-lock.yaml — файл, который команда записала. Прогноз: сколько пакетов добавит pnpm, если зависимостей в package.json две?

{
  "name": "notes-api",
  "private": true,
  "dependencies": {
    "dayjs": "^1.11.10",
    "debug": "^4.3.4"
  }
}

Progress: resolved 1, reused 0, downloaded 0, added 0
Packages: +3
+++
Progress: resolved 3, reused 3, downloaded 0, added 3, done

dependencies:
+ dayjs 1.11.21
+ debug 4.4.3

Done in <время> using pnpm v11.17.0

Пакетов три: debug тянет ms, которого в package.json нет. reused 3, downloaded 0 — все три нашлись в общем хранилище pnpm. В lock-файле три раздела, у каждого своя работа. importers — решения для package.json: у каждой зависимости записан specifier, диапазон как он написан, и выбранная version. packages — что ставить: у каждой версии integrity, хеш sha512 её архива. Отдай реестр под тем же номером другой архив, хеш не сойдётся, и установка остановится. snapshots — граф: debug@4.4.3 получает ms ровно 2.1.3, хотя в package.json самого debug записан диапазон ^2.1.3. Lock-файл фиксирует и то, чего вы сами не выбирали.

Повторим четвёртую строку модели на настоящем pnpm. Lock-файл тот же, а в package.json диапазон debug поднят до ^4.4.0. Записанная 4.4.3 под новый диапазон подходит. Флаг --frozen-lockfile запрещает pnpm менять lock-файл — так установка идёт в CI. Прогноз: поставит ли pnpm пакеты, раз подходящая версия уже записана?

{
  "name": "notes-api",
  "private": true,
  "dependencies": {
    "dayjs": "^1.11.10",
    "debug": "^4.4.0"
  }
}

✓ Lockfile passes supply-chain policies (verified <когда> ago)
[ERR_PNPM_OUTDATED_LOCKFILE] Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to date with <ROOT>/package.json

Note that in CI environments this setting is true by default. If you still need to run install in such cases, use "pnpm install --no-frozen-lockfile"

  Failure reason:
  specifiers in the lockfile don't match specifiers in package.json:
* 1 dependencies are mismatched:
  - debug (lockfile: ^4.3.4, manifest: ^4.4.0)

Не поставил и вышел с кодом 1. pnpm сравнивает строки: в lock-файле ^4.3.4, в package.json ^4.4.0, значит, решение принималось для другого пожелания, и неважно, что 4.4.3 подходит под оба. У npm проверка другая: npm ci в npm 11.17.0 смотрит, подходит ли записанная версия под новый диапазон. Эту правку он пропустил бы, а ~4.3.4 — уже нет: 4.4.3 под тильду не подходит, и npm ci останавливается с ошибкой, что package.json и package-lock.json не согласованы. Итог у обоих один: в CI lock-файл не переписывается. Подсказка в выводе говорит и то, что в CI --frozen-lockfile включён сам, без флага. Первая строка с галочкой — проверка lock-файла по правилам pnpm 11, тому самому запрету на слишком свежие версии; вердикт взят из кеша, отсюда verified … ago.

Отсюда рабочее правило: диапазон меняют только вместе с lock-файлом — pnpm install у себя, оба файла одним коммитом, и lock-файл приложения всегда лежит в git. Почему в Dockerfile их копируют раньше исходников, разбирает статья «Образ из монорепо: слои как кеш». А возраст версий, пометки deprecated и предварительные версии на latest по package.json и lock-файлу будет проверять скрипт из статьи «Свой аудитор зависимостей».

# pnpm-workspace.yaml монорепо учебника, приведён как есть
packages:
  - apps/*
  - packages/*

allowBuilds:
  # нативный резолвер импортов, нужен eslint-import-resolver-typescript
  # (тянется из eslint-config-expo); без своего postinstall не находит бинарник
  unrs-resolver: true
  # нужен drizzle-kit
  esbuild: true
  # оптимизация изображений Next.js
  sharp: true
  # телеметрия, приезжает со swagger-ui-dist (@nestjs/swagger) — не нужна
  '@scarf/scarf': false
  # postinstall только генерирует служебные файлы для веб-SDK Firebase,
  # а мы используем нативный @react-native-firebase — сборка не нужна
  '@firebase/util': false
  protobufjs: false

minimumReleaseAgeExclude:
  - '@expo/image-utils@0.11.5'
  - '@expo/require-utils@57.0.5'
  - expo-constants@57.0.14
  - expo-notifications@57.0.14