Кэш модулей: идентичность, синглтоны и дубликаты копий

Кэш ключуется разрешённым абсолютным путём

Когда ты вызываешь require("./config"), Node сначала разрешает спецификатор в единственный абсолютный путь — скажем, /srv/app/config.js — и использует этот путь как ключ в require.cache. В первый раз случается промах кэша: Node читает файл, оборачивает его в функцию, выполняет один раз и сохраняет получившийся объект module (его exports — это то, что ты получаешь) под этим ключом. Каждый последующий require(), разрешающийся в тот же путь, — это попадание в кэш: Node полностью пропускает выполнение и отдаёт ту же ссылку на объект. Холодное выполнение парсит и запускает файл (миллисекунды для реального модуля, который открывает пул или читает конфиг); попадание — это поиск по карте, микросекунды, часто разница в 100–1000×.

// config.js — evaluated exactly once
console.log("config evaluating");        // prints on the FIRST require only
module.exports = { db: "postgres://...", loadedAt: Date.now() };

// app.js
const a = require("./config");
const b = require("./config");
console.log(a === b);                     // true — same object reference
console.log(a.loadedAt === b.loadedAt);   // true — body never re-ran

// require.cache is keyed by the resolved absolute path
console.log(Object.keys(require.cache));  // [ '/srv/app/app.js', '/srv/app/config.js' ]
const id = require.resolve("./config");   // '/srv/app/config.js'
console.log(require.cache[id].exports === a); // true

Этот единственный механизм и есть причина, по которой модуль Node ведёт себя как синглтон. Если ты разместишь пул БД, объект конфига или шину EventEmitter на уровне модуля и экспортируешь её, кэш гарантирует, что каждый импортирующий разделяет единственный экземпляр — на каждый разрешённый путь существует ровно один объект module.exports, созданный при первой загрузке и переиспользуемый вечно. Ты не писал паттерн синглтона; кэш модулей и есть паттерн синглтона. Идентичность экземпляра, которую это даёт, — вся причина, по которой require("./pool") из сорока файлов разделяют один пул соединений, вместо того чтобы открыть сорок.

ESM тоже кэширует — но «отимпортировать» нельзя

ES-модули получают ту же гарантию однократности через другую структуру: карту модулей, ключуемую разрешённым URL модуля (file:///srv/app/config.mjs). Тело ES-модуля выполняется ровно один раз при первом импорте, и каждый последующий import этого URL возвращает то же пространство имён модуля. Критичное для синьора отличие — это аварийный выход, которого не существует: поддерживаемого способа инвалидировать кэш ESM нет. CommonJS позволяет залезть в require.cache и delete-нуть запись; у карты модулей ESM нет публичного API, чтобы выселить URL. «Отимпортировать» модуль нельзя.

// Единственный способ заставить ESM перевычислиться — сменить КЛЮЧ, то есть URL.
// Dev-трюк: cache-busting строка запроса делает URL другим:
const fresh = await import(`./plugin.mjs?t=${Date.now()}`); // NEW key → re-evaluates

Это работает, потому что ./plugin.mjs?t=1 и ./plugin.mjs?t=2 — это разные URL, так что каждый становится свежей записью в карте модулей. Но это утечка памяти, а не механизм перезагрузки: каждая отдельная строка запроса добавляет в карту модулей постоянную запись (модули никогда не собираются из неё сборщиком мусора), так что вотчер, который переимпортирует при каждом изменении файла, накапливает тысячи осиротевших экземпляров модулей и неуклонно наращивает RSS. Это допустимо в одноразовом dev-цикле; это никогда не продакшен-хотрелоад. Перезагрузка в продакшене означает новый процесс под супервизором, а не растущую карту модулей.

Режим отказа: две копии, которые не знают друг о друге

Вот где кэш превращается в продакшен-инцидент. Когда две версии — или две точки установки даже одной и той же версии — пакета разрешаются в разные пути, ты получаешь два отдельных экземпляра модуля, у каждого свой module.exports, свои классы, своё состояние на уровне модуля. Последствия коварны, потому что ничто не падает:

• instanceof тихо возвращает false через границу. class Token копии A и class Token копии B — это разные функциональные объекты с разными прототипами, так что Token, созданный A, проваливает проверку value instanceof Token относительно класса B. Твоя валидация просто отвергает валидные объекты или принимает невалидные, без всякой ошибки.
• Две шины событий. Как в завязке: EventEmitter копии A и копии B никогда не видят emit друг друга. Подписчики одного глухи к другому.
• Два «синглтона». Два объекта конфига, два реестра, два пула соединений — ты задаёшь значение на одном и читаешь undefined с другого.
• React «Invalid hook call». React держит свой диспетчер в состоянии на уровне модуля; две копии React означают, что твой компонент рендерится против одной копии, а хуки разрешаются против другой, и React бросает Hooks can only be called inside a component / you might have more than one copy of React.
• Расщеплённые реестры Symbol. Библиотека, использующая приватный для модуля Symbol как бренд, не может распознать объекты, помеченные её другой копией.

// node_modules/lib/index.js (copy A)        and a nested copy B at
// node_modules/plugin/node_modules/lib/index.js — SAME source, two paths
class Token {}
module.exports = { Token, make: () => new Token() };

// app pulls copy A; plugin pulls copy B
const a = require("lib");                 // resolves to copy A's path
const t = require("plugin").makeToken();  // built by copy B's Token
console.log(t instanceof a.Token);        // false — different class objects, no error

Диагностика механична, как только ты знаешь причину: npm ls <pkg> печатает дерево зависимостей и показывает, когда пакет появляется в двух версиях/местах; require.resolve("pkg") из двух точек вызова показывает два разных абсолютных пути — это и есть улика. Исправления нацелены на дедупликацию: npm dedupe сплющивает совместимые копии в одну, overrides (npm/pnpm) или resolutions (Yarn) форсируют единственную версию, объявление общей библиотеки как peerDependency (чтобы хост предоставлял одну копию, вместо того чтобы каждый пакет тащил свою) — стандартное исправление для экосистем плагинов, а сборщики предлагают явный dedupe/alias, чтобы схлопнуть копии в сборке. Цифры важны: две копии библиотеки в 300 КБ не просто рискуют корректностью — они примерно удваивают вес этой библиотеки в бандле и в резидентной памяти, потому что каждый путь — это отдельный модуль, который загружается и остаётся загруженным.

Хак хотрелоада delete require.cache[id]

Поскольку CommonJS выставляет require.cache как записываемый объект, заманчивый трюк — delete require.cache[require.resolve("./handler")], чтобы следующий require переисполнил файл, — хотрелоад для бедных. Он опасен, и все причины — это причины идентичности. Удаление записи кэша не меняет ничего, что уже держит старый exports: замыкание, зарегистрированный маршрут, слушатель события или другой модуль, захвативший const h = require("./handler"), по-прежнему указывает на старый объект. Так что теперь у тебя старый код работает для всего, что загрузилось до удаления, и новый код для всего, что после, — две версии живут одновременно, с несовпадениями instanceof между ними. Каждая перезагрузка ещё и утекает памятью: осиротевший старый экземпляр модуля (и всё, на что он ссылался) остаётся достижимым через эти устаревшие замыкания и никогда не собирается, так что куча долгоживущего вотчера растёт от перезагрузки к перезагрузке. И она тихо ломает гарантию синглтона — всю причину, по которой ты использовал модуль, — чеканя второй module.exports, пока первый ещё в ходу. Настоящий хотрелоад (тот эргономичный, что в dev-серверах) работает, снося и пересоздавая новый процесс или воркер, и никогда не мутируя кэш модулей одного процесса на месте.