Развёртывание React на GitHub Pages

.jpg)

Введение

Если у вас есть проект и вы хотите бесплатно разместить его в интернете без покупки домена, GitHub Pages — отличное решение. GitHub Pages преобразует репозитории в веб-сайты и позволяет размещать неограниченное количество страниц проекта.

Развёртывание React-приложения с навигацией требует дополнительных настроек по сравнению со статическим сайтом. В этом руководстве мы пройдём весь процесс: от создания репозитория до опубликованного сайта.

Что вам потребуется

• Аккаунт на GitHub
• Node.js и npm (или yarn)
• Git
• Базовые навыки командной строки и работы с React

Краткое определение: HashRouter — роутер, который использует часть URL после символа # для маршрутизации внутри SPA, что делает его совместимым с GitHub Pages.

Шаг 1 — Создать React-приложение

Если у вас уже есть React-проект, пропустите этот раздел.

В терминале выполните команду для быстрого создания приложения:

npx create-react-app react-gh

Перейдите в папку проекта и запустите приложение:

cd react-gh
npm start

Откройте проект в редакторе кода. В папке src удалите всё, кроме App.js и index.js. Замените содержимое App.js на следующее:

function App() {
  return (
    

      
Github Pages
      
Deploying React to Github
    
  );
}

export default App;

Шаг 2 — Добавить маршрутизацию

Установите пакет маршрутизации:

npm install react-router-dom

В App.js добавьте ссылку на страницу «О проекте»:

import { Link } from "react-router-dom";

function App() {
  return (
    

      About
      
Github Pages
      
Deploying React to Github
    
  );
}

export default App;

Создайте компонент About (файл About.js) с простой ссылкой «Домой»:

import { Link } from "react-router-dom";

const About = () => {
  return (
    

      Home
      
About Page
    
  );
};

export default About;

Теперь настройте маршруты в index.js, используя HashRouter:

import React from "react";
import ReactDOM from "react-dom";
import App from "./App";
import { HashRouter, Routes, Route } from "react-router-dom";
import About from "./About";

ReactDOM.render(
  
    
      
        } />
        } />
      
    
  ,
  document.getElementById("root")
);

Важно: используем HashRouter вместо BrowserRouter. BrowserRouter при прямом обновлении страниц на GitHub Pages приведёт к 404, потому что сервер GitHub Pages не знает о внутренних маршрутах SPA.

После правок закоммитьте изменения:

git add .
git commit -m "Create React app"

Шаг 3 — Создать репозиторий на GitHub

Перейдите в свой аккаунт GitHub и создайте новый репозиторий с тем же именем, что и проект (например, react-gh).

Добавьте удалённый репозиторий и отправьте код:

git remote add origin https://github.com//.git

git branch -M main
git push --set-upstream origin main

Шаг 4 — Развёртывание на GitHub Pages

Установите пакет gh-pages, который создаёт ветку gh-pages и публикует сборку:

npm install gh-pages --save-dev

В package.json добавьте поле homepage и скрипты deploy:

"homepage": "https://.github.io//",
"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build",
  "start": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "eject": "react-scripts eject"
}

Запустите развёртывание:

npm run deploy

После успешного выполнения вы сможете открыть приложение по адресу:

https://.github.io/

Когда HashRouter не подходит

• Если вы хотите использовать пользовательский домен и серверную конфигурацию (например, настроить правила на сервере), BrowserRouter может быть предпочтителен, но потребует дополнительной настройки сервера.
• Если вам нужна красивая структура URL без #, рассмотрите развёртывание на Netlify, Vercel или настроенный собственный сервер.

Чеклист развёртывания (коротко)

• Создан React-проект (или использован существующий)
• Установлен react-router-dom
• Реализованы компоненты и ссылки
• В index.js использован HashRouter
• Коммиты добавлены в Git
• Создан репозиторий на GitHub
• Установлен gh-pages и добавлено homepage в package.json
• Выполнен npm run deploy и сайт доступен по URL

Playbook: быстрый SOP для повторяемого развёртывания

1. Обновить код, убедиться, что все изменения закоммичены.
2. Убедиться, что package.json содержит корректный homepage.
3. Локально запустить npm run build для проверки сборки.
4. Выполнить npm run deploy.
5. Проверить URL и navigate по нескольким маршрутам.
6. Если не работает — очистить кеш браузера и проверить консоль разработчика и вкладку Network.

Типичные ошибки и как их решать

• 404 при обновлении страницы: вы используете BrowserRouter — переключитесь на HashRouter или настройте сервер.
• Неправильный путь в homepage: убедитесь, что указан https://.github.io// (заканчивается слэшем).
• Ошибка gh-pages: попробуйте установить gh-pages как dev-зависимость и повторить deploy, проверьте права доступа к репозиторию.

Ментальная модель: почему HashRouter работает на GitHub Pages

GitHub Pages обслуживает статические файлы из одной точки. BrowserRouter полагается на серверную поддержку «чистых» URL (без #). HashRouter использует часть URL после # (которая не отправляется на сервер) — весь роутинг происходит на стороне клиента, поэтому сервер всегда возвращает index.html, и маршруты работают.

Критерии приёмки

• Сайт открывается по адресу https://.github.io/
• Перемещение между «Home» и «About» через ссылки не вызывает 404
• Повторная загрузка любой страницы SPA не приводит к ошибке на сервере

Короткая инструкция для сотрудничества (role-based)

• Разработчик: обновляет код, проверяет локально через npm start, создает PR.
• Ответственный за релиз: проверяет package.json, запускает npm run deploy и подтверждает работу по URL.
• Владелец репозитория: проверяет, что homepage указан верно и что GitHub Pages активирован в настройках репозитория (обычно это делается автоматически при наличии ветки gh-pages).

Дополнительные варианты и альтернативы

• Для «чистых» URL и автоматического CI используйте Netlify или Vercel — они поддерживают SPA без # и предоставляют простые правила редиректа.
• Для блога рассмотрите Jekyll (поддерживается нативно GitHub Pages).

Заключение

GitHub Pages — быстрый способ бесплатно опубликовать фронтенд-приложение. Если нужно простое размещение React SPA с минимальными настройками — используйте HashRouter и gh-pages. Для более сложных требований (чистые URL, серверные настройки) лучше выбрать платформы с поддержкой перенаправлений или собственный хостинг.

Важно: сохраняйте репозиторий упорядоченным, автоматизируйте сборку и развёртывание через CI, если проект начинает расти.

Короткое объявление: Развёртывание React на GitHub Pages занимает несколько минут: создайте приложение, добавьте HashRouter, настройте package.json и выполните npm run deploy — сайт будет онлайн.