CLI Node.js — запуск, отладка и деплой

ДЛЯ НОВИЧКОВ

Разработчику Архитектору

---

Запуск, отладка и деплой Node.js

Материал опирается на первую программу (node app.js, npm run dev). Далее — флаги Node, dev-перезапуск, отладка в VS Code и Chrome, Docker и минимальный чеклист перед production.

Установка Node и nvm — в Node.js — основы. npm-скрипты — 265.md.

---

Запуск Node.js

Команда	Назначение
node	REPL — интерактивный JS
node file.js	Выполнить файл
node -v	Версия runtime
node -e "console.log(1+1)"	Однострочник
node --watch server.js	Перезапуск при изменении (Node 18.11+)
node --inspect-brk file.js	Отладка с паузой на старте

REPL

node

> 2 + 2
4
> .exit

Последний результат — в _. Выход: .exit, Ctrl+D (Unix) или дважды Ctrl+C.

Dev-перезапуск

Встроенный watch (без зависимости):

"scripts": {
  "dev": "node --watch src/server.js"
}

nodemon — привычный вариант в учебных проектах:

npm install -D nodemon

"dev": "nodemon src/server.js"

nodemon следит за большим набором файлов; node --watch — только за импортами entry-файла (поведение уточняйте по версии Node).

---

Полезные флаги node --help

Флаг	Зачем
--max-old-space-size=4096	Лимит памяти кучи (МБ)
--trace-warnings	Стек для предупреждений
--import ./preload.mjs	Загрузить модуль до скрипта
NODE_OPTIONS=--enable-source-maps	Карты исходников в стеке ошибок

Переменные:

• NODE_ENV=production — флаг для библиотек (не меняет скорость сам по себе);
• UV_THREADPOOL_SIZE=8 — пул потоков libuv для fs, crypto (по умолчанию 4).

---

npm-скрипты в работе

npm run dev
npm start
npm test

Цепочки в package.json:

"build": "rimraf dist && tsc",
"postinstall": "prisma generate"

На Windows для env используйте cross-env — см. 265.md.

start.bat на Windows

Для запуска двойным щелчком из Проводника:

@echo off
cd /d "%~dp0"
where node >nul 2>&1 || (echo Node.js не найден. & pause & exit /b 1)
call npm start
pause

cd /d "%~dp0" — рабочая папка = папка bat-файла. pause оставляет окно с логом после ошибки.

---

Отладка

VS Code

.vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Запустить API",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}/src/server.js"
    }
  ]
}

F5 — breakpoints в .js / .ts (с source maps после tsc).

Chrome DevTools

node --inspect-brk src/server.js

Откройте chrome://inspect → Open dedicated DevTools for Node. Удобно для профиля CPU и heap snapshots.

Подробнее про IDE — Отладка.

---

Graceful shutdown

При SIGTERM / SIGINT (Ctrl+C, остановка контейнера):

process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);

function shutdown() {
  server.close(() => {
    // закрыть pool БД, таймеры
    process.exit(0);
  });
  setTimeout(() => process.exit(1), 10_000);
}

Сначала перестать принимать соединения, завершить текущие запросы, затем выйти.

---

Docker (production-ориентир)

Многоступенчатый образ уменьшает размер и поверхность атаки:

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=builder /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

.dockerignore:

node_modules
.git
.env

Слушать 0.0.0.0, не только 127.0.0.1, если контейнер должен принимать внешние подключения. Health-check endpoint — GET /health.

Разбор типовых образов — Dockerfile — 10 типовых образов.

---

Деплой без Docker

На своём VPS чаще всего ставят pm2 или systemd и проксируют через Nginx. PaaS вроде Render и Railway принимают push в Git, собирают проект и запускают node dist/server.js. Serverless подходит только если укладываетесь в лимиты времени и cold start.

Платформа	Типичный подход
VPS	pm2 или systemd + Nginx
Render / Railway	Git push, build, node dist/server.js
Serverless	Адаптер под лимиты платформы

PM2:

npm install -g pm2
pm2 start src/index.js --name notes-api
pm2 save

---

Production-чеклист

• .nvmrc или engines + одна версия Node в CI
• npm ci в пайплайне, lock в Git
• Секреты в env платформы, не в образе
• GET /health и при необходимости /ready
• Структурированные логи, обработка unhandledRejection
• HTTPS за reverse proxy
• Лимит тела запроса (express.json({ limit: '1mb' }))

Сравнение Express / Fastify / Nest — в 26.md и 263.md.

---

Связанные материалы

• Node.js — основы
• Структура проекта
• Fullstack и хостинг
• Справочник: CLI и деплой

---

Основа по протоколу

Прокси Nginx перед Node — Nginx — конфиги под задачу.