Что такое npm
npm (Node Package Manager) - менеджер пакетов для JavaScript. Он ставит библиотеки в проект, запоминает их версии, запускает скрипты разработки и сборки и публикует ваши пакеты в общем реестре npm. Устанавливается npm вместе с Node.js, поэтому отдельной установки не требует: достаточно один раз поставить Node по инструкции в статье про установку Node.js.
Проверьте, что всё работает:
node -v
npm -v
Если обе команды выводят версии, можно начинать. Все команды ниже выполняются в терминале из папки проекта.
Команда npm init: создание проекта и package.json
Любой проект на Node.js начинается с файла package.json. В нём хранятся имя проекта, версия, список зависимостей и скрипты. Создайте папку и инициализируйте проект:
mkdir my-app
cd my-app
npm init -y
Ключ -y принимает все вопросы по умолчанию и создаёт готовый package.json. Без ключа npm задаст вопросы по очереди: имя, версию, описание, точку входа, лицензию. Файл можно потом править руками.
{
"name": "my-app",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"license": "ISC"
}
Это сокращённый пример результата npm init -y: в вашей версии npm могут быть и другие поля, например description, keywords и author. Если нужны ES-модули, добавьте в файл строку "type": "module". Проверить, что JSON написан корректно, поможет онлайн-форматтер JSON: лишняя запятая в package.json ломает любую команду npm.
Форматирование и проверка JSON
Команда npm install: локальная и глобальная установка
Основная команда npm - установка пакетов. По умолчанию пакет ставится локально, то есть в папку node_modules внутри проекта, а его имя и версия записываются в package.json.
npm install express
npm install lodash@4
npm install --save-dev eslint
npm install -g typescript
Первая строка ставит Express и добавляет его в раздел dependencies. Вторая ставит пакет lodash версии 4.x. Третья (сокращённо npm i -D eslint) ставит eslint как зависимость для разработки (devDependencies). Последняя устанавливает TypeScript глобально, то есть доступным в любой папке как команда.

Если запустить npm install без имени, npm прочитает package.json и поставит все перечисленные зависимости. Так вы разворачиваете скачанный из репозитория проект: после клонирования достаточно этой команды.
| Команда | Что делает |
|---|---|
npm install (или npm i) | Ставит все зависимости из package.json |
npm install имя | Ставит пакет локально и записывает в dependencies |
npm install -D имя | Ставит пакет для разработки (devDependencies) |
npm install -g имя | Ставит пакет глобально |
npm uninstall имя | Удаляет пакет и убирает его из package.json |
npm ci | Чистая установка строго по package-lock.json |
npm ls | Показывает дерево установленных пакетов |
npm outdated | Показывает пакеты, для которых есть новые версии |
npm update | Обновляет пакеты в рамках допустимых версий |
npm audit | Проверяет зависимости на известные уязвимости |
npm run имя | Запускает скрипт из package.json |
npx пакет | Запускает пакет без глобальной установки |
Ставьте глобально только инструменты командной строки, которыми пользуетесь в разных проектах. Библиотеки для кода держите локально, иначе версии у разных проектов будут конфликтовать. Если на Linux или macOS npm просит права администратора при глобальной установке, не запускайте его через sudo, а настройте каталог для глобальных пакетов или используйте менеджер версий nvm.
Файлы package.json и package-lock.json
В package.json записаны версии с диапазонами. Знак вставки ^4.17.1 разрешает обновления до следующей мажорной версии (4.x.x), а тильда ~4.17.1 разрешает только исправления (4.17.x). Точный номер без знаков фиксирует версию строго.
Файл package-lock.json создаётся автоматически и хранит точные версии всех установленных пакетов, включая вложенные зависимости. Благодаря ему у всех членов команды и на сервере ставится один и тот же набор. Этот файл нужно коммитить в Git, а редактировать руками не следует. Если при слиянии веток он конфликтует, поможет разбор конфликтов в package-lock.json.
Папку node_modules в Git не добавляют: она большая и восстанавливается командой npm install. Добавьте её в .gitignore.
node_modules/
.env
Этот фрагмент .gitignore исключает из репозитория установленные пакеты и файл с секретами.
Чем отличаются npm install и npm ci
Обе команды ставят зависимости, но по-разному. npm install учитывает package.json, может обновить package-lock.json и подходит для повседневной работы. npm ci удаляет node_modules и ставит всё строго по lock-файлу, не меняя его, а при расхождении с package.json останавливается с ошибкой. Поэтому npm ci применяют на сервере сборки и в CI, а npm install на своём компьютере. Подробное сравнение есть в статье, какую из двух команд выбрать.
Скрипты в package.json и npm run
Раздел scripts позволяет задать короткие имена для длинных команд. Это стандартный способ запускать сервер разработки, сборку и тесты.
{
"scripts": {
"start": "node index.js",
"dev": "node --watch index.js",
"build": "echo Сборка выполнена",
"lint": "eslint ."
}
}
Теперь работают команды npm start (для start и test пишется без run), npm run dev, npm run build и npm run lint. Флаг --watch у Node перезапускает скрипт при изменении файла, отдельный пакет для этого больше не нужен.
Чтобы передать аргументы скрипту, добавьте двойное тире: npm run lint -- --fix. Запрос "npm run dev" в инструкциях к Vite, Next.js и другим инструментам означает просто запуск такого скрипта.
Внутри скриптов доступны программы из node_modules/.bin: пишите eslint ., не указывая путь. Если нужно вызвать скрипт на Windows и в Linux одинаково, избегайте команд, специфичных для одной системы. Типичная проблема описана в статье про ошибку bash в скриптах npm.
Команда npx: запуск без установки
npx входит в состав npm и запускает программу из пакета, не устанавливая её глобально. Сначала он ищет команду в локальном node_modules, а если её нет, скачивает пакет во временное хранилище.
npx create-vite@latest my-vite-app
npx eslint .
npx http-server -p 8080
Первая команда запускает генератор проекта на Vite, вторая проверяет код локальным eslint, третья поднимает простой статический сервер на порту 8080. Перед запуском незнакомого пакета проверьте его страницу на npmjs.com, ведь код скачивается и выполняется сразу.
Обновление пакетов и самого npm
Чтобы увидеть, что устарело, выполните npm outdated. В таблице будут столбцы Current (установлена), Wanted (максимум по диапазону из package.json) и Latest (последняя в реестре).
npm outdated
npm update
npm install lodash@latest
npm install -g npm@latest
npm update обновит пакеты только в пределах диапазонов из package.json. Чтобы перейти на новую мажорную версию, установите пакет с @latest и проверьте, что проект работает. Последняя команда обновляет сам npm, но проще всего получать свежий npm вместе с очередной версией Node.js. Если версия Node привязана к проекту, переключайтесь через nvm.
Проверка безопасности
Команда npm audit сверяет установленные пакеты с базой известных уязвимостей и выводит список по уровням (low, moderate, high, critical). Ключ npm audit fix пытается обновить уязвимые пакеты без нарушения диапазонов версий.
Не применяйте npm audit fix --force вслепую: он может поставить новые мажорные версии и сломать проект. Сначала посмотрите отчёт, а затем обновляйте проблемные пакеты вручную и запускайте тесты. Часть предупреждений относится к инструментам разработки и не влияет на готовый сайт.
Частые ошибки npm
- npm: command not found или "не является внутренней или внешней командой". Node.js не установлен или не добавлен в PATH; переустановите и откройте новое окно терминала.
- "невозможно загрузить файл ... npm.ps1, выполнение сценариев отключено" в Windows PowerShell. Политика выполнения скриптов запрещает запуск. Запустите команду в cmd, либо выполните в PowerShell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. - EACCES: permission denied. Нет прав на папку при глобальной установке; настройте каталог для глобальных пакетов, а не используйте sudo.
- ERESOLVE unable to resolve dependency tree. Конфликт версий; обновите пакеты или запустите установку с
--legacy-peer-deps, если уверены в совместимости. - Предупреждения npm WARN deprecated. Пакет помечен как устаревший; это не ошибка, но стоит заменить его на поддерживаемый.
- Сломанные зависимости после смены ветки. Удалите node_modules и выполните
npm ci. Для поиска лишнего поможет статья о проверке неиспользуемых пакетов.
