Як встановити React.js на Windows VPS: Повний посібник з налаштування

React.js — це бібліотека JavaScript з відкритим вихідним кодом, яку підтримує Meta (раніше Facebook), для побудови компонентних користувацьких інтерфейсів, зокрема односторінкових застосунків (SPA), що динамічно оновлюють DOM без повного перезавантаження сторінки. Встановлення React на Windows VPS — замість локальної робочої станції — надає постійне, віддалено доступне середовище розробки з виділеними ресурсами, що робить його ідеальним для командної співпраці, CI/CD-конвеєрів і розгортання на стейджингу.

Цей посібник охоплює кожен крок встановлення React.js виробничого рівня на Windows VPS: від налаштування середовища виконання Node.js та керування змінними середовища до створення структури проєкту, роботи сервера розробки та виведення виробничої збірки. Також розглядаються неочевидні збої, на які натрапляють інженери, що дотримуються поверхневих інструкцій.

Чому варто встановлювати React на Windows VPS, а не на локальному хості

Запуск середовища розробки React на VPS Хостингу замість локальної машини вирішує кілька реальних проблем:

• Постійна доступність: Сервер розробки залишається запущеним навіть коли ваша локальна машина вимкнена, що дозволяє віддаленим членам команди або QA-тестувальникам отримати доступ до живого URL-перегляду в будь-який час.
• Узгоджене середовище: Кожен розробник підключається до однієї й тієї ж ОС, версії Node та дерева залежностей, що усуває помилки типу «працює на моїй машині».
• Ізоляція ресурсів: Ресурсомісткі збірки (npm run build, великі компіляції Webpack) не знижують продуктивність вашої локальної робочої станції.
• Відповідність стейджингу: Windows VPS відображає цільове середовище розгортання, коли ваш виробничий стек також базується на Windows Server (IIS, гібридні архітектури ASP.NET).
• Віддалена доступність: Ви можете відкрити сервер розробки на певному порту та отримати до нього доступ з будь-якого браузера, де завгодно.

Якщо ваше навантаження зрештою масштабується до обслуговування скомпільованих ресурсів React разом із Node.js API, розгляньте перехід на середовище Виділених серверів для гарантованої пропускної здатності I/O та відсутності ефекту «галасливого сусіда».

Передумови

Перед початком переконайтеся, що на вашому Windows VPS виконані такі умови:

• Windows Server 2016 / 2019 / 2022 або Windows 10/11 (64-розрядна версія)
• Доступ адміністратора або підвищеного рівня через RDP
• Вихідний доступ до інтернету на VPS (для завантаження інсталяторів та пакетів npm)
• Щонайменше 2 GB RAM — компіляція Webpack у пам’яті є ресурсомісткою; 4 GB рекомендовано для проєктів із більш ніж кількома залежностями
• Текстовий редактор або IDE — Visual Studio Code є де-факто стандартом для розробки на React

Крок 1: Встановлення Node.js на Windows

1.1 Завантаження LTS-релізу

React не вимагає абсолютно останнього релізу Node.js. Канал LTS (Long Term Support) є правильним вибором для будь-якого середовища, де важлива стабільність.

1. Відкрийте браузер на вашому VPS (або завантажте віддалено та перенесіть через буфер обміну RDP).
2. Перейдіть на https://nodejs.org.
3. Завантажте Windows Installer (.msi) для поточної LTS-версії (наприклад, 20.x або 22.x).

Важлива примітка: Завжди завантажуйте 64-розрядний інсталятор .msi, а не архів .zip. .msi автоматично обробляє реєстрацію PATH, інтеграцію служб та залежність Visual C++ Redistributable. Архів .zip вимагає ручного налаштування PATH і є поширеним джерелом помилок нерозпізнавання npm.

1.2 Запуск інсталятора

Запустіть завантажений файл .msi та дотримуйтесь інструкцій майстра:

1. Прийміть ліцензійну угоду.
2. Залиште шлях призначення за замовчуванням (C:Program Filesnodejs), якщо у вас немає конкретної причини його змінювати.
3. На екрані Custom Setup переконайтеся, що всі наступні компоненти позначені:

• Node.js runtime
• npm package manager
• Add to PATH (це найважливіший прапорець — якщо не позначено, жоден термінал не розпізнає node або npm)
• Online documentation shortcuts (необов’язково)

1. На екрані Tools for Native Modules позначте «Automatically install the necessary tools», якщо ви плануєте використовувати будь-які пакети npm, що вимагають нативної компіляції (node-gyp, bcrypt, sharp тощо). Це автоматично встановить Chocolatey, Python та Visual Studio Build Tools.
2. Завершіть встановлення та перезапустіть термінальну сесію (або всю RDP-сесію, якщо зміни PATH не відображаються одразу).

1.3 Перевірка встановлення

Відкрийте нове вікно PowerShell або Command Prompt (не те, що було відкрите до встановлення — воно не матиме оновленого PATH) та виконайте:

node -v

npm -v

Обидві команди повинні повернути рядки версій. Якщо будь-яка з них повертає 'node' is not recognized as an internal or external command, PATH не було налаштовано правильно. Дивіться розділ усунення несправностей нижче.

Приклад очікуваного виводу:

v20.14.0
10.7.0

1.4 Налаштування глобального каталогу пакетів npm (необов’язково, але рекомендовано)

За замовчуванням npm встановлює глобальні пакети в C:Users<username>AppDataRoamingnpm. У спільному або багатокористувацькому середовищі Windows Server це може спричинити конфлікти дозволів. Щоб встановити власний глобальний каталог:

npm config set prefix "C:npm-global"

Потім додайте C:npm-global до системного PATH через System Properties > Environment Variables > System Variables > Path.

Крок 2: Створення структури React-застосунку

2.1 Сучасний підхід: Vite (рекомендовано замість Create React App)

Оригінальна стаття рекомендує create-react-app (CRA). Це застаріла порада. CRA був офіційно визнаний застарілим на початку 2023 року і більше не підтримується основною командою React. Сама документація React більше не рекомендує його для нових проєктів.

Поточні рекомендовані інструменти для створення структури:

Для простого SPA на Windows VPS Vite є правильним вибором у 2024 році та надалі.

2.2 Створення нового React-проєкту з Vite

Відкрийте PowerShell та перейдіть до каталогу ваших проєктів:

cd C:Projects

Створіть структуру нового React-проєкту:

npm create vite@latest my-react-app -- --template react

Щоб використовувати TypeScript (настійно рекомендовано для будь-якого нетривіального проєкту):

npm create vite@latest my-react-app -- --template react-ts

Перейдіть до каталогу проєкту та встановіть залежності:

cd my-react-app
npm install

2.3 Якщо вам необхідно використовувати Create React App (застарілі проєкти)

Якщо ви підтримуєте застарілу кодову базу, що вимагає CRA, використовуйте npx для запуску без глобального встановлення:

npx create-react-app my-react-app

Не запускайте npm install -g create-react-app. Підхід із глобальним встановленням є застарілим і завантажить застарілу кешовану версію. Використання npx завжди отримує останню доступну версію з реєстру.

Крок 3: Запуск сервера розробки

3.1 Запуск сервера розробки

Для проєкту на основі Vite:

npm run dev

Для проєкту на основі CRA:

npm start

Обидві команди запускають локальний сервер розробки. Vite за замовчуванням використовує http://localhost:5173; CRA — http://localhost:3000.

3.2 Відкриття сервера розробки на Windows VPS (віддалений доступ)

На локальній машині сервер розробки доступний лише з localhost. На VPS зазвичай потрібно отримати до нього доступ із локального браузера через інтернет. Необхідні дві зміни:

Прив’язати сервер до всіх мережевих інтерфейсів:

Для Vite відредагуйте vite.config.js (або vite.config.ts):

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    host: '0.0.0.0',
    port: 5173,
  },
})

Для CRA встановіть змінну середовища HOST перед запуском:

set HOST=0.0.0.0
npm start

Відкрийте порт у брандмауері Windows:

netsh advfirewall firewall add rule name="React Dev Server" dir=in action=allow protocol=TCP localport=5173

Після цього ви можете отримати доступ до сервера розробки за адресою http://<your-vps-ip>:5173 з будь-якого браузера.

Попередження щодо безпеки: Ніколи не відкривайте сервер розробки у публічний інтернет на виробничому VPS без автентифікації. Використовуйте зворотний проксі (Nginx або IIS з URL Rewrite) або VPN-тунель для будь-якого середовища, що обробляє реальні дані.

Крок 4: Структура проєкту та ключові файли

Розуміння структури, створеної інструментом, запобігає плутанині під час початку модифікації файлів:

my-react-app/
├── public/             # Static assets served as-is (favicon, robots.txt)
├── src/
│   ├── assets/         # Images, fonts imported by components
│   ├── App.jsx         # Root component
│   ├── App.css         # Root component styles
│   ├── main.jsx        # Entry point — mounts <App /> into index.html
│   └── index.css       # Global styles
├── index.html          # HTML shell — Vite injects the bundle here
├── vite.config.js      # Vite configuration
├── package.json        # Dependencies and scripts
└── node_modules/       # Installed packages (never commit this)

Файл src/main.jsx є точкою входу застосунку. Він викликає ReactDOM.createRoot() для монтування кореневого компонента в div #root у index.html. Кожен компонент, який ви створюєте, зрештою буде імпортовано в це дерево.

Крок 5: Збірка для виробництва

Коли застосунок готовий до розгортання, згенеруйте оптимізовану статичну збірку:

npm run build

Ця команда викликає бандлер Vite на основі Rollup (або Webpack для CRA), який:

• Транспілює JSX та сучасний JavaScript у сумісний з браузером ES5/ES2015+
• Видаляє невикористаний код із пакету (tree-shaking)
• Мінімізує JavaScript, CSS та HTML
• Генерує імена файлів із хешем вмісту для довгострокового кешування браузером
• Виводить все до каталогу dist/ (Vite) або build/ (CRA)

Щоб переглянути виробничу збірку локально перед розгортанням:

npm run preview

Вміст dist/ — це суто статичні файли (HTML, JS, CSS, ресурси). Їх може обслуговувати будь-який веб-сервер — IIS на Windows Server, Nginx, Apache або служба статичного хостингу.

Розгортання збірки на IIS у Windows Server

Якщо ваш VPS запускає IIS, налаштуйте новий сайт, що вказує на папку dist/. Оскільки SPA на React використовують клієнтську маршрутизацію, необхідно додати правило URL Rewrite для перенаправлення всіх 404-помилок назад до index.html:

<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="React SPA" stopProcessing="true">
          <match url=".*" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          </conditions>
          <action type="Rewrite" url="/index.html" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

Без цього правила будь-яка пряма навігація до маршруту на кшталт /dashboard повертатиме 404 від IIS замість завантаження React-застосунку.

Якщо ви обслуговуєте React-фронтенд разом із бекенд API і потребуєте керованого середовища панелі управління, VPS з cPanel може спростити налаштування віртуальних хостів та завершення SSL.

Крок 6: Захист застосунку за допомогою HTTPS

Виробничий React-застосунок повинен обслуговуватися через HTTPS. Браузери блокують запити зі змішаним вмістом, а багато браузерних API (service workers, геолокація, буфер обміну) обмежені безпечними контекстами.

Для розгортання на VPS:

1. Отримайте SSL-сертифікат для вашого домену. AlexHost надає SSL-сертифікати, які можна встановити безпосередньо на вашому VPS.
2. Налаштуйте IIS або ваш зворотний проксі для завершення TLS на порту 443 та перенаправлення HTTP (порт 80) на HTTPS.
3. Встановіть змінну середовища HTTPS у значення true, якщо використовуєте вбудований сервер CRA для локального тестування HTTPS.

Якщо у вас ще немає домену, що вказує на ваш VPS, спочатку зареєструйте його через Реєстрацію доменів та налаштуйте DNS A-запис, що вказує на IP-адресу вашого VPS.

Крок 7: Усунення поширених проблем

node або npm не розпізнається

Це означає, що каталог встановлення Node.js відсутній у системному PATH. Виправте це вручну:

1. Натисніть Win + R, введіть sysdm.cpl, натисніть Enter.
2. Перейдіть до Advanced > Environment Variables.
3. У розділі System Variables знайдіть Path та натисніть Edit.
4. Додайте C:Program Filesnodejs як новий запис.
5. Натисніть OK у всіх діалогових вікнах, потім відкрийте нове вікно термінала.

Помилки EACCES або відмови в доступі під час npm install

На Windows Server це зазвичай виникає при запуску npm від імені обмеженого користувача. Або запустіть PowerShell від імені адміністратора, або налаштуйте кеш npm та глобальні каталоги на шлях, яким поточний користувач володіє:

npm config set cache "C:npm-cache"
npm config set prefix "C:npm-global"

Порт вже використовується

Якщо порт 5173 або 3000 зайнятий іншим процесом:

netstat -ano | findstr :5173

Визначте PID в останньому стовпці, потім:

taskkill /PID <PID> /F

Або змініть порт у vite.config.js або передайте --port як прапорець:

npm run dev -- --port 3001

npm ERR! code EINTEGRITY (невідповідність контрольної суми)

Це вказує на пошкоджений кеш npm. Очистіть його та повторіть спробу:

npm cache clean --force
npm install

Повільний npm install при першому запуску

Початкове встановлення залежностей для React-проєкту може тривати 2–5 хвилин залежно від пропускної здатності мережі VPS та дискового I/O. Якщо це постійно завершується тайм-аутом, перевірте, чи має VPS вихідний доступ до registry.npmjs.org на порту 443. Деякі політики брандмауера дата-центрів блокують це за замовчуванням.

Матриця рішень: вибір правильного налаштування React для вашого VPS

Практичний контрольний список ключових висновків

• Встановлюйте LTS-реліз Node.js за допомогою інсталятора .msi, а не архіву .zip, для забезпечення автоматичної реєстрації PATH.
• Використовуйте npx create vite@latest для всіх нових React-проєктів — CRA є застарілим і не повинен використовуватися для нової розробки.
• На VPS встановіть host: '0.0.0.0' у vite.config.js та відкрийте відповідний порт брандмауера для віддаленого доступу до сервера розробки.
• Додайте правило URL Rewrite для IIS, щоб перенаправляти всі запити, що не є файлами чи каталогами, до index.html — без нього клієнтська маршрутизація ламається при прямому доступі до URL.
• Завжди обслуговуйте виробничі збірки через HTTPS; отримайте та встановіть SSL-сертифікат перед запуском у виробництво.
• Запустіть npm run build та перевірте вивід dist/ перед розгортанням — перевірте розміри пакетів за допомогою npm run build -- --report або vite-bundle-visualizer.
• Ніколи не додавайте node_modules/ до системи контролю версій; завжди додавайте його до .gitignore.
• Якщо для різних проєктів потрібні різні версії Node, встановіть nvm-windows для керування ними без глобального перевстановлення Node.js.

Часті запитання

Чи потрібно «встановлювати» React.js на сервер, чи достатньо лише виводу збірки?

React сам по собі є залежністю часу збірки. Виробничий вивід npm run build — це звичайний HTML, CSS та JavaScript — для його обслуговування на сервері не потрібен Node.js runtime. Node.js потрібен лише на машині, де ви запускаєте процес збірки.

У чому різниця між npm run dev та npm run build?

npm run dev запускає сервер розробки з гарячою заміною модулів (HMR) та немінімізованими картами джерел — він не оптимізований для продуктивності і ніколи не повинен використовуватися для обслуговування виробничого трафіку. npm run build створює мінімізований, оброблений tree-shaking, статичний пакет із хешем вмісту, призначений для розгортання.

Чому Create React App є застарілим і що використовувати натомість?

CRA покладається на Webpack 4, який має значно повільніший час збірки та HMR порівняно з ESM-нативним сервером розробки Vite. Команда React офіційно видалила CRA зі своєї документації у 2023 році та тепер рекомендує Vite для SPA, Next.js для full-stack застосунків та Remix для застосунків із великою кількістю даних.

Чи можна запускати кілька React-проєктів на одному Windows VPS одночасно?

Так. Кожен проєкт запускає свій сервер розробки на різному порту. Налаштуйте vite.config.js кожного проєкту з унікальним значенням port, відкрийте кожен порт у брандмауері Windows та за бажанням налаштуйте IIS як зворотний проксі для маршрутизації піддоменів або шляхів до відповідного порту.

Як зберегти сервер розробки React запущеним після закриття RDP-сесії?

Використовуйте менеджер процесів. Встановіть PM2 глобально (npm install -g pm2) та запустіть сервер розробки як керований процес: pm2 start npm --name "react-dev" -- run dev. PM2 підтримує процес активним незалежно від термінальної сесії та може бути налаштований на перезапуск при перезавантаженні системи.