Как да инсталирате и конфигурирате Node.js и NPM на Windows

Node.js е JavaScript среда за изпълнение с отворен код, за различни платформи, изградена върху V8 двигателя на Chrome, която изпълнява JavaScript код извън браузър. NPM (Node Package Manager) е мениджърът на пакети по подразбиране, включен в Node.js, предоставящ достъп до над два милиона пакети за многократна употреба. Заедно те формират основния инструментариум за изграждане на сървърни приложения, CLI инструменти, REST API и full-stack JavaScript проекти на Windows.

Това ръководство обхваща пълния работен процес за инсталиране, проверка, конфигуриране и създаване на първо приложение с Node.js и NPM на Windows — включително управление на версиите, отстраняване на проблеми с PATH, обхват на глобални и локални пакети, и производствени съображения, които повечето уроци пропускат.

Избор на правилната версия на Node.js преди инсталиране

Графикът за издания на Node.js следва предвидим ритъм, който пряко влияе на вашия избор:

LTS версиите носят четни главни номера на версии (напр. 20.x, 22.x) и получават критични корекции за сигурност в продължение на 30 месеца. Current изданията носят нечетни главни номера на версии и преминават към LTS статус след шест месеца, ако отговарят на критериите за стабилност.

За повечето разработчици и сървърни разгръщания — включително приложения, хоствани на VPS Хостинг — LTS е правилният избор. Клонът Current е подходящ само когато конкретно се нуждаете от функция на V8 или Node.js API, която все още не е налична в активния LTS ред.

NVM за Windows: Професионалната алтернатива на директната инсталация

Преди да продължите с MSI инсталатора, помислете дали се нуждаете от nvm-for-windows (Node Version Manager за Windows). Директният инсталатор обвързва системата ви с единична версия на Node.js. NVM ви позволява да инсталирате множество версии едновременно и да превключвате между тях за всеки проект — критично при поддържане на стари кодови бази заедно с модерни.

Инсталирайте nvm-for-windows от официалната му страница с издания в GitHub, след което използвайте:

“`

nvm install 20.14.0

nvm use 20.14.0

nvm list

“`

Ако управлявате един проект или учите Node.js за първи път, MSI инсталаторът е достатъчен. За професионални среди NVM е силно препоръчителен.

Стъпка 1: Изтегляне на инсталатора на Node.js

1. Отидете на официалния уебсайт на Node.js на адрес nodejs.org.
2. Изберете раздела LTS и изтеглете Windows Installer (`.msi`) за вашата архитектура. Почти всички съвременни Windows машини са 64-битови (`node-v20.x.x-x64.msi`). ARM64 компилации са налични за Windows на ARM устройства.
3. Проверете SHA-256 контролната сума на изтегления файл спрямо стойностите, публикувани на страницата за изтегляния на Node.js, преди да стартирате инсталатора. Тази стъпка е задължителна във всяка среда, съобразена със сигурността.

За проверка на контролната сума в PowerShell:

“`powershell

Get-FileHash .node-v20.14.0-x64.msi -Algorithm SHA256

“`

Сравнете резултата с публикувания хеш. Несъответствие означава повредено или манипулирано изтегляне.

Стъпка 2: Инсталиране на Node.js и NPM

1. Щракнете двукратно върху изтегления файл `.msi`, за да стартирате съветника за инсталиране.
2. Щракнете Next на екрана за добре дошли.
3. Приемете Лицензионното споразумение с крайния потребител и щракнете Next.
4. Пътят за инсталиране по подразбиране е `C:Program Filesnodejs`. Освен ако нямате конкретна причина да го промените (напр. несистемно устройство за управление на дисковото пространство), оставете го непроменен.
5. На екрана Custom Setup потвърдете, че npm package manager е избран. По подразбиране е активиран.
6. На екрана Tools for Native Modules ще видите опция за автоматично инсталиране на Chocolatey, Python и Visual Studio Build Tools. Отметнете тази кутия, ако очаквате да инсталирате NPM пакети, включващи нативни C++ добавки (напр. `bcrypt`, `sharp`, пакети, зависещи от `node-gyp`). Тази стъпка инсталира няколко гигабайта инструменти — пропуснете я, ако се нуждаете само от чисто JavaScript пакети.
7. Щракнете Install, след това Finish.

Инсталаторът автоматично регистрира `node.exe` и `npm.cmd` в системната ви променлива на средата `PATH` под `C:Program Filesnodejs`.

Какво всъщност прави инсталаторът на вашата система

Разбирането на страничните ефекти предотвратява бъдещи главоболия при отстраняване на грешки:

• Добавя `C:Program Filesnodejs` към System PATH (достъпен за всички потребители).
• Създава `C:Users<username>AppDataRoamingnpm` като префикс за глобални пакети по подразбиране.
• Регистрира Node.js в регистъра на Windows под `HKLMSOFTWARENode.js`.
• Инсталира `npx` (изпълнителят на NPM пакети) заедно с `npm`.

Стъпка 3: Проверка на инсталацията

Отворете нов прозорец на Command Prompt или PowerShell. Квалификаторът „нов” е важен — съществуващите терминални сесии кешират стария PATH и няма да отразят промените на инсталатора.

“`

node -v

“`

Очакван резултат: `v20.14.0` (или вашата инсталирана версия)

“`

npm -v

“`

Очакван резултат: `10.x.x`

“`

npx -v

“`

Очакван резултат: съвпада или е близо до версията на npm

Ако `node` не се разпознава, PATH не е актуализиран правилно. Поправете го ръчно:

1. Отворете System Properties > Advanced > Environment Variables.
2. Под System variables намерете `Path` и щракнете Edit.
3. Добавете `C:Program Filesnodejs`, ако липсва.
4. Щракнете OK, затворете всички терминални прозорци и ги отворете отново.

Диагностициране на често срещани проблеми след инсталиране

Проблем: `npm` се разпознава, но `node` не се разпознава (или обратното).

Причина: Непълен запис в PATH или конфликтна инсталация от Chocolatey или предишна настройка на NVM.

Решение: Изпълнете `where node` и `where npm`, за да идентифицирате кои двоични файлове се разрешават. Премахнете остарелите записи.

Проблем: Грешки с разрешения `EACCES` при изпълнение на `npm install -g`.

Причина: Директорията с глобалния префикс няма права за запис за текущия потребител.

Решение: Променете глобалния префикс към директория, притежавана от потребителя (разгледано в Стъпка 5).

Проблем: `node` отваря Microsoft Store вместо да стартира Node.js.

Причина: Windows 10/11 се доставя с App Execution Alias за `node`, който пренасочва към Store.

Решение: Отидете на Settings > Apps > App execution aliases и деактивирайте псевдонимите за `python.exe` и `node.exe` (ако са налични).

Стъпка 4: Актуализиране на NPM до най-новата версия

Версията на NPM, включена в инсталатора на Node.js, обикновено е с една или две второстепенни версии зад текущото издание. Актуализирайте я веднага след инсталирането:

“`

npm install -g npm@latest

“`

Флагът `-g` инсталира пакета в директорията с глобалния префикс, правейки го достъпен в цялата система. След актуализацията проверете отново:

“`

npm -v

“`

Важен граничен случай: На Windows актуализирането на NPM глобално понякога може да остави остарял `npm.cmd` в `C:Program Filesnodejs`, сочещ към старата версия, докато новата версия е инсталирана в `C:Users<username>AppDataRoamingnpm`. Ако `npm -v` все още показва старата версия след актуализацията, проверете кой двоичен файл е пръв в PATH:

“`

where npm

“`

Пътят под `AppDataRoamingnpm` трябва да се появи преди `C:Program Filesnodejs` в резултата. Ако не е така, пренаредете записите в PATH съответно.

Стъпка 5: Конфигуриране на NPM за вашата среда

Конфигурацията на NPM се съхранява в файл `.npmrc`, който може да съществува на три нива: за проект, за потребител (`C:Users<username>.npmrc`) и глобално (`C:Program Filesnodejsnode_modulesnpmnpmrc`). Настройките за проект заменят настройките за потребител, които заменят глобалните настройки.

Промяна на глобалния префикс на пакети

Глобалният префикс по подразбиране (`AppDataRoamingnpm`) работи за повечето потребители, но на споделени сървъри или когато се прилагат квоти за диск, може да искате да го пренасочите:

“`

npm config set prefix "D:NodeGlobal"

“`

След промяна на префикса добавете новата поддиректория `bin` към вашия PATH:

“`

setx PATH "%PATH%;D:NodeGlobal"

“`

Конфигуриране на частен или огледален регистър

Корпоративните среди и сървърите без достъп до интернет често използват частен NPM регистър (Verdaccio, Nexus, Artifactory):

“`

npm config set registry "https://your-private-registry.example.com/"

“`

За удостоверяване срещу частен регистър:

“`

npm login –registry=https://your-private-registry.example.com/

“`

За пакети с обхват (напр. `@mycompany/*`) можете да насочите само този обхват към частен регистър, като оставите публичния регистър непроменен:

“`

npm config set @mycompany:registry "https://your-private-registry.example.com/"

“`

Конфигуриране на HTTP прокси

Ако вашата Windows машина се намира зад корпоративен прокси:

“`

npm config set proxy "http://proxy.company.com:8080"

npm config set https-proxy "http://proxy.company.com:8080"

“`

Преглед на всички текущи настройки

“`

npm config list

npm config list –json

“`

Флагът `–json` извежда конфигурация, четима от машина, полезна за скриптове и диагностика на CI/CD тръбопроводи.

Полезна справка за конфигурацията на NPM

Стъпка 6: Създаване и стартиране на Node.js приложение

Инициализиране на проекта

“`

mkdir my-node-app

cd my-node-app

npm init -y

“`

`npm init -y` генерира `package.json` с настройки по подразбиране, извлечени от името на директорията и вашата NPM потребителска конфигурация. Файлът `package.json` е манифестът на вашето приложение — той дефинира входната точка, скриптовете, зависимостите и метаданните.

Изграждане на основен HTTP сървър

Създайте `app.js` в директорията на проекта:

“`javascript

// app.js

const http = require('http');

const hostname = '127.0.0.1';

const port = 3000;

const server = http.createServer((req, res) => {

res.statusCode = 200;

res.setHeader('Content-Type', 'text/plain');

res.end('Hello, World!n');

});

server.listen(port, hostname, () => {

console.log(`Server running at http://${hostname}:${port}/`);

});

“`

Стартирайте го:

“`

node app.js

“`

Отидете на `http://127.0.0.1:3000/` в браузъра си. Трябва да видите `Hello, World!`.

Техническа бележка: Node.js използва еднонишков цикъл на събития, подкрепен от libuv за I/O операции. Обратното извикване `http.createServer` се задейства при всяка входяща заявка, без да блокира цикъла. Тази архитектура прави Node.js изключително ефективен за I/O-натоварени работни натоварвания, но неподходящ за CPU-интензивни задачи без работни нишки или дъщерни процеси.

Добавяне на фреймуърка Express

Express е де факто стандартният HTTP фреймуърк за Node.js, предоставящ маршрутизиране, поддръжка на middleware и чиста абстракция на заявка/отговор:

“`

npm install express

“`

Това инсталира Express локално (в `node_modules/`) и го записва като зависимост в `package.json`. Актуализирайте `app.js`:

“`javascript

const express = require('express');

const app = express();

const port = 3000;

app.get('/', (req, res) => {

res.send('Hello from Express!');

});

app.listen(port, () => {

console.log(`Server running at http://localhost:${port}`);

});

“`

“`

node app.js

“`

Посетете `http://localhost:3000/`, за да потвърдите отговора.

Разбиране на `node_modules` и `.gitignore`

Директорията `node_modules` може да съдържа стотици мегабайти файлове. Никога не я включвайте в системата за контрол на версиите. Създайте файл `.gitignore`:

“`

node_modules/

.env

“`

Сътрудниците и тръбопроводите за разгръщане възстановяват зависимостите чрез изпълнение на `npm install`, което чете `package.json` и `package-lock.json`, за да възпроизведе точното дърво на зависимостите.

Стъпка 7: Управление на пакети — локални срещу глобални

Разбирането на разликата между локална и глобална инсталация на пакети е един от най-честите източници на объркване за новодошлите в Node.js.

Основно правило: Ако даден пакет предоставя инструмент за командния ред, който искате да е достъпен навсякъде (напр. `nodemon`, `eslint`, `typescript`), инсталирайте го глобално. Ако е библиотека, която приложението ви импортира с `require()` или `import`, инсталирайте я локално.

Стартиране на приложения в производство с PM2

За всяко Node.js приложение, разгърнато на сървър — независимо дали на инстанция VPS Хостинг или Dedicated Server — директното изпълнение на `node app.js` е недостатъчно. Процесът ще се прекрати, ако терминалът се затвори или възникне необработено изключение.

PM2 е стандартният мениджър на процеси за Node.js в производство:

“`

npm install -g pm2

pm2 start app.js –name "my-app"

pm2 startup

pm2 save

“`

`pm2 startup` генерира команда за конфигуриране на PM2 да рестартира приложението ви автоматично при рестартиране на системата. `pm2 save` запазва текущия списък с процеси.

Стъпка 8: Укрепване на сигурността и одит

Изпълнение на одит на зависимостите

“`

npm audit

“`

NPM кръстосано препраща инсталираните ви пакети спрямо базата данни за препоръки на GitHub. Всички известни уязвимости се докладват с нива на сериозност (ниска, умерена, висока, критична) и пътища за отстраняване.

“`

npm audit fix

“`

Това автоматично надгражда уязвимите пакети до най-близката некъртеща коригирана версия. При къртещи промени прегледайте резултата и надградете ръчно.

Фиксиране на версиите на зависимостите

В `package.json` NPM използва диапазони на семантично версиониране по подразбиране (`^1.2.3` позволява второстепенни и корекционни актуализации). В производство фиксирайте точни версии, за да предотвратите изненади от веригата на доставки:

“`

npm config set save-exact true

“`

Или ръчно заменете префиксите `^` с точни низове на версии в `package.json` и включете файла `package-lock.json` в контрола на версиите.

Избягване на стартиране на NPM като администратор

Изпълнението на `npm install -g` с повишени привилегии записва файлове, притежавани от акаунта на администратора, което може да причини грешки с разрешения при последващи операции без повишени права. Конфигурирайте глобален префикс, притежаван от потребителя (вижте Стъпка 5), за да премахнете изцяло необходимостта от повишени привилегии.

Разгръщане на Node.js приложения на сървър

Локалното разработване е само първият етап. Производственото разгръщане въвежда допълнителни изисквания: управление на процеси, обратно проксиране, TLS прекратяване и управление на променливи на средата.

Типичен производствен стек на Linux VPS Хостинг инстанция съчетава Node.js с Nginx като обратен прокси. Nginx обработва TLS прекратяването (използвайки сертификати от доставчик като SSL Сертификати) и препраща заявките към процеса на Node.js, слушащ на локален порт.

За екипи, предпочитащи управлявана среда с контролен панел, VPS с cPanel предоставя управление на Node.js приложения чрез интерфейса на cPanel, опростявайки разгръщането без необходимост от директна SSH конфигурация.

Конфигурацията, специфична за средата (идентификационни данни за база данни, API ключове, номера на портове), никога не трябва да бъде твърдо кодирана. Използвайте файл `.env` с пакета `dotenv`:

“`

npm install dotenv

“`

“`javascript

require('dotenv').config();

const port = process.env.PORT || 3000;

“`

Матрица за решения: Кога да използвате всеки метод за инсталиране

Ключови технически изводи

• Винаги инсталирайте версията LTS за производствени и екипни среди. Използвайте изданието Current само когато е необходима конкретна функция на V8 или Node.js API.
• Използвайте nvm-for-windows във всяка среда, където трябва да съществуват едновременно множество версии на Node.js.
• Проверявайте SHA-256 контролната сума на инсталатора преди изпълнение.
• Променете глобалния NPM префикс към директория, притежавана от потребителя, за да избегнете грешки с разрешения и да премахнете необходимостта от повишени привилегии.
• Никога не включвайте `node_modules/` в контрола на версиите. Винаги включвайте `package-lock.json`.
• Изпълнявайте `npm audit` след всеки `npm install` в производствени тръбопроводи.
• Използвайте PM2 за управление на процеси при всяко сървърно разгръщане — никога не изпълнявайте `node app.js` директно в производство.
• Прекратявайте TLS на слоя на обратния прокси (Nginx, Caddy), а не вътре в процеса на Node.js за по-добра производителност и управление на сертификати.
• Съхранявайте тайните в променливи на средата, заредени чрез `dotenv`, никога в изходния код.

Често задавани въпроси

Каква е разликата между Node.js LTS и Current на Windows?

LTS версиите получават корекции за сигурност и стабилност в продължение на 30 месеца и носят четни главни номера на версии (18, 20, 22). Current версиите включват най-новите езикови и runtime функции, но се поддържат само шест месеца, преди да преминат към LTS или да бъдат прекратени. За производствени разгръщания на Windows винаги използвайте LTS.

Защо `npm install -g` се проваля с грешка за разрешения на Windows?

Глобалният префикс по подразбиране (`C:Users<username>AppDataRoamingnpm`) понякога няма права за запис поради UAC политики или предишни инсталации, изпълнени като администратор. Решението е или да стартирате терминала като администратор (не се препоръчва дългосрочно), или да преконфигурирате глобалния префикс към директория, притежавана от вашия потребителски акаунт, с `npm config set prefix "C:yourpath"`.

Мога ли да изпълнявам множество версии на Node.js едновременно на Windows?

Да, използвайки nvm-for-windows. Инсталирайте го, след което използвайте `nvm install <version>` и `nvm use <version>`, за да превключите активния runtime. Всяка версия поддържа собствена директория с глобални пакети, предотвратявайки конфликти между версиите.

Какво е `package-lock.json` и трябва ли да го включа в контрола на версиите?

`package-lock.json` е точен, детерминистичен запис на цялото дърво на зависимостите, разрешено по време на `npm install`. Той гарантира, че всеки разработчик и всяко CI/CD изпълнение инсталира идентични версии на пакети. Винаги го включвайте в контрола на версиите и никога не го редактирайте ръчно.

Как да стартирам Node.js приложение автоматично при стартиране на Windows без сървър?

За машини за разработка използвайте PM2 с `pm2 startup` и `pm2 save`. За интеграция с Windows Service инструменти като `node-windows` обвиват Node.js процес като нативна Windows Service, позволявайки управление чрез Services MMC snap-in и автоматично рестартиране при повреда или рестартиране.