Что находится в файле package-lock.json?

Что находится в файле package-lock.json?

package-lock.json — это критически важный файл в Node.js проектах, который фиксирует точные версии всех установленных зависимостей и их подзависимостей на момент выполнения npm install.

Основное назначение

Файл выполняет роль lock-файла (замка версий). Когда вы разрабатываете приложение и установили зависимости, package-lock.json записывает точный момент этого состояния. Благодаря этому все разработчики команды, CI/CD pipeline и production-серверы получают одинаковую версию каждого пакета.

Структура package-lock.json

{
  "name": "my-app",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "my-app",
      "version": "1.0.0",
      "dependencies": {
        "react": "^18.2.0"
      }
    },
    "node_modules/react": {
      "version": "18.2.3",
      "resolved": "https://registry.npmjs.org/react/-/react-18.2.3.tgz",
      "integrity": "sha512-...",
      "requires": {
        "loose-envify": "^1.1.0"
      }
    }
  }
}

Ключевые данные в package-lock.json

1. version — точная версия установленного пакета (например, 18.2.3, а не ^18.2.0)
2. resolved — URL на npm registry, откуда был загружен пакет
3. integrity — SHA-512 хеш, который проверяет целостность архива при загрузке
4. requires — список зависимостей этого пакета (его подзависимостей)
5. lockfileVersion — версия формата самого lock-файла (влияет на совместимость с версиями npm)

Почему package-lock.json важен?

1. Воспроизводимость среды

Без lock-файла: npm install → может установить разные версии минорных обновлений
С lock-файлом: npm install → гарантирует идентичную версию везде

2. Безопасность

• Хеш integrity проверяет, что пакет не был скомпрометирован при загрузке
• Защищает от атак с подменой архивов

3. Скорость установки

• npm не нужно резолвить все зависимости — просто использует данные из lock-файла
• Заметно быстрее первого npm install

Когда обновляется package-lock.json?

• При выполнении npm install (если изменился package.json)
• При выполнении npm update
• При выполнении npm audit fix
• Не нужно редактировать вручную — npm сам управляет файлом

Best Practices

✅ Коммить package-lock.json в Git

git add package-lock.json

✅ Использовать npm ci вместо npm install в CI/CD

# Development
npm install  # может обновить package-lock.json

# CI/CD и production
npm ci  # использует package-lock.json, не обновляет

❌ Не редактировать вручную

❌ Не игнорировать в .gitignore

Аналоги в других экосистемах

• Python: requirements.lock или poetry.lock
• Ruby: Gemfile.lock
• Java: pom.xml (частично)
• Go: go.sum

package-lock.json — это гарант стабильности и предсказуемости работы Node.js приложения. Его правильное использование предотвращает "работает на моей машине" проблемы и обеспечивает одинаковую версионирование зависимостей по всему стеку разработки и развёртывания.