Как развернуть Vite React проект на Timeweb Cloud

После прекращения поддержки create-react-app многие разработчики перешли на Vite для сборки React-приложений. Однако при попытке задеплоить проект на хостинге Timeweb Cloud возникают типичные ошибки: пустая страница, 404 или некорректная загрузка ресурсов. В этой статье объясняем, как правильно настроить Vite для деплоя на Timeweb Cloud, и разбираем частые проблемы.

Почему Vite проект не работает на Timeweb Cloud?

Основная причина - неверно указан базовый путь (base) в конфиге Vite. По умолчанию Vite предполагает, что приложение разворачивается в корень домена. На Timeweb Cloud проект может располагаться в подпапке или иметь специфическую структуру. Кроме того, сервер хостинга не обрабатывает клиентские маршруты React Router, что приводит к 404 при прямом переходе на страницу.

Настройка vite.config.js для Timeweb Cloud

Для корректной работы добавьте в vite.config.js параметр base. Если сайт расположен в корне домена, укажите base: '/'. Если в подпапке - например, /my-app/. Также обязательно настройте fallback для SPA с помощью плагина или .htaccess.

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

export default defineConfig({
  plugins: [react()],
  base: '/', // или '/subfolder/' для подпапки
  build: {
    outDir: 'dist',
    sourcemap: false,
    emptyOutDir: true,
  },
  server: {
    port: 3000,
    host: true,
  },
  resolve: {
    alias: {
      '@': '/src',
    },
  },
});

Как правильно собрать проект для деплоя

Запустите сборку командой npm run build или yarn build. В папке dist появится готовый статический набор файлов. Загрузите содержимое папки dist на хостинг Timeweb Cloud через FTP или файловый менеджер в панели управления. Убедитесь, что точка входа - index.html.

Решение проблемы с 404 для SPA (React Router)

Если вы используете React Router, при прямом переходе на страницу (например, /about) сервер возвращает 404, так как не знает о клиентской маршрутизации. На Timeweb Cloud создайте файл .htaccess в корне папки проекта со следующим содержимым:

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

Этот код перенаправляет все запросы на index.html, позволяя React Router обработать маршруты.

Частые ошибки и их исправление

• Пустая страница после деплоя - проверьте параметр base в vite.config.js. Если ресурсы загружаются с неверным путём, исправьте его.
• Ошибка 500 - убедитесь, что права доступа к файлам установлены корректно (644 для файлов, 755 для папок).
• Не отображаются изображения - используйте абсолютные пути или импортируйте изображения через JS (import img from './img.png').
• Sourcemaps в продакшене - отключите sourcemap: true в конфиге сборки, чтобы уменьшить размер бандла и ускорить загрузку.

Заключение

Деплой Vite React проекта на Timeweb Cloud не требует сложных манипуляций. Достаточно правильно указать базовый путь, настроить рерайтинг для SPA и загрузить собранные файлы. Следуя этой инструкции, вы сможете избежать типичных ошибок и успешно развернуть приложение. Если остались вопросы - обратитесь к документации Vite или создайте тикет в поддержку Timeweb Cloud.