Для чего используется package-lock.json?

Для чего используется package-lock.json?

Определение

package-lock.json — это специальный файл, который автоматически создаётся npm и содержит точные версии всех установленных зависимостей (включая вложенные). Это файл блокировки, который гарантирует, что все разработчики работают с одинаковыми версиями пакетов.

Основная проблема, которую она решает

package.json с ошибкой гибкости версий:

{
  "dependencies": {
    "express": "^4.18.0"
  }
}

Символ ^ означает "любая версия от 4.18.0 до 5.0.0". Если в вашем проекте используется express 4.18.2, а коллега установит — может быть 4.19.0. Это может привести к несовместимости.

Что находится в package-lock.json

{
  "name": "my-app",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "my-app",
      "version": "1.0.0",
      "dependencies": {
        "express": "4.18.2"
      }
    },
    "node_modules/express": {
      "version": "4.18.2",
      "resolved": "https://registry.npmjs.org/express/-/express-4.18.2.tgz",
      "integrity": "sha512-5...",
      "dependencies": {
        "body-parser": "1.20.0",
        "router": "1.3.5"
      }
    },
    "node_modules/body-parser": {
      "version": "1.20.0",
      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.0.tgz",
      "integrity": "sha512-..."
    }
  }
}

Ключевая информация:

• version — точная версия пакета (не с диапазонами)
• resolved — URL откуда скачана библиотека
• integrity — хеш файла для проверки целостности
• dependencies — все зависимости пакета (вложенные)

Главные назначения

1. Воспроизводимость (Reproducibility)

Когда вы добавляете package-lock.json в git и коммитите его:

# Разработчик A
нpm install
# Устанавливаются версии из package-lock.json

# Разработчик B
npm install
# Устанавливаются точно такие же версии!

Без package-lock.json каждый мог бы получить разные версии.

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

package-lock.json содержит хеш (integrity) каждого пакета:

"integrity": "sha512-abc123def456..."

Eсли пакет был подменён или скачан с ошибкой, npm обнаружит несовпадение хеша.

3. Оптимизация установки (Installation Speed)

package-lock.json содержит полное дерево зависимостей, поэтому npm не нужно резрешать зависимости снова:

# Без package-lock.json
npm install  # Долго! npm вычисляет дерево

# С package-lock.json
npm install  # Быстро! уже всё известно

Практические сценарии

Сценарий 1: Работа в команде

# Developer A добавляет библиотеку
npm install express
# package.json: "express": "^4.18.0"
# package-lock.json: "express": "4.18.2" (вместе с хешом)

# Коммит в git
git add package.json package-lock.json
git commit -m "add express"

# Developer B обновляет репозиторий
git pull
npm install
# Устанавливает express 4.18.2 (не 4.19.0!)

Сценарий 2: CI/CD Pipeline

# GitHub Actions, GitLab CI, Jenkins
npm ci  # Вместо npm install!

Команда npm ci (ci = clean install) использует только package-lock.json, игнорируя package.json зависимости. Это гарантирует, что в production попадут точно такие же версии.

Сценарий 3: Production deployment

# На продакшене используем npm ci
npm ci --production
# Гарантирует точные версии без surprises

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

npm install / npm i

Обновляет dependencies и package-lock.json согласно package.json:

npm install

npm update

Обновляет версии до последних в диапазонах package.json:

npm update
# Обновляет express до 4.18.3 (если доступна)
# Обновляет package-lock.json

npm install --save package

Добавляет новый пакет и обновляет оба файла:

npm install --save lodash
# package.json: "lodash": "^4.17.21"
# package-lock.json: "lodash": "4.17.21" + хеш

Лучшие практики

1. Коммитить package-lock.json

# ✅ Правильно
git add package.json package-lock.json
git commit

# ❌ Неправильно: добавлять в .gitignore
echo "package-lock.json" >> .gitignore

2. Использовать npm ci в CI/CD

# GitHub Actions
steps:
  - name: Install dependencies
    run: npm ci  # Не npm install!

3. Разрешать диапазоны в package.json, но фиксировать в lock

{
  "dependencies": {
    "express": "^4.18.0"  // Разрешаем 4.18.x
  }
}

// package-lock.json
"express": "4.18.2"  // Но фиксируем конкретную версию

Различия npm vs yarn vs pnpm

npm: package-lock.json
yarn: yarn.lock
pnpm: pnpm-lock.yaml

Все служат одной цели — фиксировать версии.

Проблемы и решения

Проблема: package-lock.json конфликты в merge

# Два разработчика добавили разные пакеты
# Возник конфликт при merge

# Решение: удалить node_modules и package-lock.json, переустановить
rm -rf node_modules package-lock.json
npm install
# npm пересоздаст package-lock.json
git add package-lock.json
git commit

Проблема: версия в package-lock.json отличается от prod

# Решение: обновить lock файл
npm install  # Пересчитает зависимости
git add package-lock.json

Реальный пример из backend проекта

# package.json
{
  "name": "my-api",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.18.0",
    "pg": "^8.8.0",
    "dotenv": "^16.0.0"
  }
}

# package-lock.json содержит точные версии
# express: 4.18.2
# pg: 8.8.0
# dotenv: 16.0.3
# + хеши для каждого

# Это гарантирует, что код одинаково работает везде

Выводы

• package-lock.json фиксирует версии всех зависимостей
• Гарантирует репродукцируемость — одинаковые версии везде
• Улучшает безопасность через проверку хешей
• Ускоряет установку — дерево зависимостей уже известно
• ДОЛЖЕН коммититься в git для командной работы
• Использовать npm ci вместо npm install в CI/CD

Это критически важный файл для правильной работы Node.js проектов в команде и на продакшене.