Развертывание приложения Vite/React на страницах GitHub — это захватывающая веха, но иногда этот процесс может сопровождаться неожиданными проблемами, особенно при работе с изображениями и ресурсами. В этом сообщении блога вы проведете вас через весь процесс: от первоначального развертывания до устранения распространенных проблем и поиска эффективных решений.

Независимо от того, являетесь ли вы новичком или человеком с опытом, это руководство поможет вам избежать распространенных ошибок и успешно развернуть приложение Vite/React со всеми правильно отображаемыми ресурсами.

Предварительные условия

Прежде чем мы углубимся, убедитесь, что у вас есть следующее:

• Проект Vite/React: в этом руководстве предполагается, что вы настроили свой проект, используя Vite в качестве инструмента сборки и React в качестве платформы.
• Репозиторий GitHub: у вас должен быть существующий репозиторий GitHub, куда вы будете отправлять свое приложение для развертывания.
• Страницы GitHub включены: убедитесь, что страницы GitHub включены в настройках вашего репозитория для развертывания.

Шаг 1. Инициализация проекта и развертывание страниц GitHub

Во-первых, убедитесь, что ваше приложение Vite/React правильно инициализировано и работает на локальном хосте. Вы можете создать базовый проект Vite следующим образом:

npm create vite@latest

Установить зависимости:

npm install

Запустите проект локально, чтобы убедиться, что все работает:

npm run dev

Как только ваш проект будет готов, отправьте его в свой репозиторий GitHub.

Создайте файл vite.config.js для страниц GitHub.

GitHub Pages ожидает, что приложение будет обслуживаться с определенного базового URL-адреса, которым обычно является имя вашего репозитория. Обновите файл vite.config.js, чтобы отразить это:

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

export default defineConfig({
  base: process.env.NODE_ENV === 'production' ? '/your-repo-name/' : '/',
  plugins: [react()],
})

Опция base гарантирует, что приложение будет использовать правильный базовый путь при развертывании.

Шаг 2. Сборка и развертывание проекта

Для развертывания вам потребуется установить пакет gh-pages.

npm install gh-pages --save-dev

В ваш package.json добавьте следующие скрипты для автоматизации процесса развертывания:

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist"
}

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

npm run deploy

На этом этапе ваш проект должен быть доступен по адресу https://.github.io//, но если вы похожи на меня, у вас могут возникнуть некоторые проблемы. приложение не отображается должным образом или изображения не отображаются.

Шаг 3. Распространенные проблемы и решения

Проблема 1: пустая страница после развертывания

После развертывания вы можете заметить, что приложение загружает пустую страницу. Это часто вызвано проблемами маршрутизации. По умолчанию используется BrowserRouter из реакции-router-dom, который опирается на маршрутизацию на стороне сервера, но GitHub Pages обслуживает статические файлы и не обрабатывает маршруты на стороне клиента.

Решение: используйте HashRouter

Чтобы решить эту проблему, переключитесь с BrowserRouter на HashRouter в файле index.js или main.jsx.

Примечание. У вас не обязательно должно быть это просто удобная библиотека пользовательского интерфейса, которую я очень часто использую в своих проектах.

import { HashRouter } from 'react-router-dom';

createRoot(document.getElementById('root')).render(
  
    
      
        
      
    
  
);

HashRouter использует символ решетки (#) в URL-адресе для отслеживания состояния навигации, что позволяет страницам GitHub правильно обслуживать различные маршруты без возврата ошибки 404.

Проблема 2: ошибка 404 при обновлении или других маршрутах

После устранения проблемы с пустой страницей вы можете столкнуться с еще одной проблемой: приложение работает на домашней странице, но показывает ошибку 404 при переходе к другим маршрутам, особенно если вы напрямую получаете доступ к такому маршруту, как /blogs или /projects.

Это происходит потому, что GitHub Pages знает только, как обслуживать файл index.html, и не распознает маршруты, управляемые React Router.

Решение: обработка ошибок 404 в настройках страниц GitHub

Чтобы это исправить, вам нужно создать файл 404.html в папке public/. Этот файл гарантирует, что GitHub Pages будет обслуживать ваш файл index.html для любых маршрутов, которые он не распознает, позволяя React Router обрабатывать маршрутизацию:

1. Скопируйте index.html в новый файл с именем 404.html.
2. Поместите этот файл в свою папку public/.
3. Пересоберите и повторно разверните проект.

Проблема 3: изображения не загружаются в производство

Одной из наиболее распространенных проблем при развертывании является неправильная загрузка изображений. Хотя они отлично работают на локальном хосте, вы можете заметить неработающие ссылки на изображения после развертывания на страницах GitHub.

Например, вы можете ссылаться на такое изображение в своих компонентах:

Проблема: неправильные пути к изображениям

Проблема здесь в том, что абсолютные пути (начинающиеся с /) не работают, когда приложение развертывается в подкаталоге (например, /your-repo-name/). GitHub Pages пытается найти изображение по адресу https://.github.io/Images/myImage.png вместо https://.github.io/your-repo-name/Images/myImage.png. , что приводит к ошибке 404.

Решение: используйте BASE_URL

Чтобы это исправить, переместите все свои изображения в папку Public/Images. Это необязательно, но я настоятельно рекомендую вам это сделать. Вы будете динамически добавлять BASE_URL к путям изображений в зависимости от среды:

1. Определите константу BASE_URL, которая зависит от среды:

   const BASE_URL = import.meta.env.BASE_URL;

1. Используйте этот BASE_URL при ссылке на изображения:

ПРИМЕЧАНИЕ. Не забудьте удалить / перед изображениями, иначе он будет удвоен: один из BASE_URL, а другой из /Images, который вы забыли удалить.

Это гарантирует, что правильный путь используется как в разработке (локальный хост), так и в рабочей среде (страницы GitHub).

Шаг 4. Окончательное развертывание

После внесения исправлений в маршрутизацию и пути к образам перестройте и повторно разверните приложение:

npm run build
npm run deploy

Теперь ваше приложение Vite/React должно быть полностью развернуто, все изображения должны быть правильно отображены, а все маршруты должным образом обработаны.

В итоге:

1. Проблемы маршрутизации: используйте HashRouter для правильной маршрутизации в статических развертываниях, таких как страницы GitHub.
2. Ошибки 404 на маршрутах: создайте файл 404.html, чтобы убедиться, что GitHub Pages корректно обслуживает ваше приложение.
3. Изображения не загружаются: переместите все изображения в папку Public/Images и динамически добавляйте BASE_URL к путям к ресурсам для работы как со средой разработки, так и с рабочей средой.

С помощью этих шагов ваше приложение Vite/React должно быть активным и бесперебойно работать на страницах GitHub. Удачного кодирования и развертывания!