pnpm patch: как исправить зависимость без форка

Почему правка node_modules вручную не является решением

Файл внутри `node_modules` легко изменить, но эта правка исчезнет после чистой установки, на машине коллеги и в CI. В результате локально баг будто бы исправлен, а production-сборка снова получает исходный пакет. `pnpm patch` превращает изменение в явный артефакт: пакет распаковывается в отдельный каталог, вы редактируете его содержимое, затем pnpm сохраняет разницу как патч и связывает её с зависимостью через конфигурацию проекта. Diff можно просмотреть в code review, проверить тестами и удалить после выхода официальной исправленной версии. Это делает временный workaround контролируемым и воспроизводимым.

Важно: Не вносите «быструю правку» прямо в `node_modules`, если исправление должно пережить следующую установку.

Как создать и зафиксировать патч

1. Уточните точную зависимость и версию: Проверьте, какая версия реально установлена и какой пакет содержит дефект. Для монорепозитория убедитесь, что правите тот resolution, который используется нужным workspace.
2. Запустите `pnpm patch <pkg>@<version>`: pnpm распакует пакет во временную директорию и выведет путь к ней. Для контролируемого расположения можно использовать поддерживаемую опцию `--edit-dir`.
3. Измените только нужные файлы: Сделайте минимальный diff: исправьте конкретный код, шаблон или ресурс. Не форматируйте весь пакет без необходимости.
4. Проверьте исправление локально: До commit патча убедитесь, что изменение действительно устраняет исходный дефект и не создаёт новый.
5. Выполните `pnpm patch-commit <path>`: Передайте путь к редактируемой директории. pnpm создаст patchfile и зарегистрирует его в `patchedDependencies`.
6. Закоммитьте патч и manifest/lockfile: В репозиторий должны попасть все файлы, от которых зависит применение патча, затем нужна чистая установка и тест CI.

Совет: Держите patch-файл маленьким и тематическим: такой diff легче проверить после обновления исходной библиотеки.

Как работает patchedDependencies и привязка к версии

В актуальной документации pnpm `patchedDependencies` представляет собой словарь: ключом может быть имя пакета, точная версия или диапазон, значением — относительный путь к patch-файлу. Точная версия имеет более высокий приоритет, затем диапазон, затем запись только по имени. Для обычного аварийного фикса безопаснее привязать патч как можно конкретнее, чтобы он не начал молча применяться к будущей версии с изменившимся исходным кодом. pnpm также сообщает об ошибках применения патча; это полезная защита при обновлении, потому что конфликт заставляет пересмотреть workaround, а не притворяется, что старый diff всё ещё корректен.

Предупреждение: Не расширяйте диапазон версии «на будущее» без проверки исходников. Патч, созданный для одной версии, может быть логически неверен для следующей.

patch, overrides или fork: что выбрать

• Исправить несколько строк в коде зависимости. pnpm patch. Минимальный воспроизводимый diff без отдельного репозитория
• Заменить версию транзитивной зависимости. overrides. Официальная документация отдельно советует не менять package.json пакета патчем ради зависимостей
• Долгая ветка со значительными изменениями. fork. Проще сопровождать историю, тесты и релизы
• Исправление уже принято upstream. обновление пакета и удаление патча. Локальный workaround больше не нужен

Что делать после обновления пакета

После bump версии сначала проверьте, существует ли исходный дефект. Если upstream исправил его, удалите запись `patchedDependencies` и patch-файл, затем выполните чистую установку и тесты. Если проблема осталась, не переносите старый файл механически: создайте новый патч от новой версии и сравните смысл изменений. Контекст строк, импортов и API мог измениться даже при похожем коде. Если patch стал большим, затрагивает публичный API или требует серии взаимозависимых изменений, это сигнал перейти к fork либо отправить pull request upstream. Локальные патчи хороши как тонкий слой адаптации, но плохо работают как скрытая параллельная версия библиотеки.

Проверка перед merge патча

• Патч устраняет один понятный дефект и не содержит случайного форматирования.
• Ключ `patchedDependencies` ограничен подходящей версией или диапазоном.
• Patch-файл находится в репозитории и попадает в пакет CI checkout.
• Чистый `pnpm install` применяет патч без ошибок.
• Тест воспроизводит проблему до патча и проходит после него, если это возможно.
• В issue/комментарии указано, почему патч нужен и при каком обновлении его можно удалить.
• Изменения зависимостей внутри package.json пакета не маскируются патчем вместо overrides.

Важно: Если патч затрагивает безопасность, криптографию или механизм обновлений, не ограничивайтесь локальным workaround без оценки upstream advisory и официального релиза.

Как сопровождать патч, чтобы он не стал техническим долгом

Добавьте короткое описание причины рядом с задачей в issue tracker или pull request: ссылка на upstream issue, версия пакета, симптом, ожидаемое условие удаления. При каждом обновлении зависимости reviewer должен видеть, что патч всё ещё нужен. Полезно иметь тест на исходный дефект — тогда удаление workaround можно проверить объективно. Не складывайте в один patch несколько независимых исправлений: их жизненный цикл может различаться. Если библиотека часто требует локальных изменений, проблема уже не в механизме `pnpm patch`; стоит оценить альтернативный пакет, полноценный fork или вклад в upstream. Так временное исправление остаётся прозрачным, а не превращается в незаметную постоянную ветку кода.

Что учитывать

Файл внутри `node_modules` легко изменить, но эта правка исчезнет после чистой установки, на машине коллеги и в CI. В результате локально баг будто бы исправлен, а production-сборка снова получает исходный пакет. `pnpm patch` превращает изменение в явный артефакт: пакет распаковывается в отдельный каталог, вы редактируете его содержимое, затем pnpm сохраняет разницу как патч и связывает её с зависимостью через конфигурацию проекта. Diff можно просмотреть в code review, проверить тестами и…

Источники и проверка

Фактическая часть сверена по первичным источникам (в т.ч. pnpm patch <pkg>). Пример и формулировки — редакция N1RO на 2026-09-20.

• pnpm patch <pkg>