Как развернуть Nuxt приложение на GitHub

Введение

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

В этой статье вы получите пошаговую инструкцию по развертыванию Nuxt-приложения на GitHub Pages с использованием GitHub Actions. Мы рассмотрим все детали: от подготовки Nuxt-репозитория до публикации production-сборки на Pages. Если вам пока не знакомы нюансы деплоя на статичный хостинг — не беспокойтесь, все этапы сопровождаются поясняющими комментариями к коду и настройкам.

Что такое Nuxt и почему GitHub Pages?

Зачем нужен Nuxt

Nuxt — это современный динамический фреймворк для Vue.js, который позволяет писать приложения серверного рендеринга (SSR), статические сайты и универсальные SPA. Nuxt значительно ускоряет старт разработки, облегчает настройку роутинга, динамических страниц и множество других задач.

Почему GitHub Pages

GitHub Pages отлично работает для хостинга статических файлов. Nuxt позволяет собрать ваше приложение в статическую версию, которой будет достаточно для большинства презентаций, лендингов, блогов или проектной документации. Это бесплатно, просто и интегрировано с экосистемой GitHub.

Подготовка Nuxt-приложения

Прежде чем публиковать приложение на GitHub Pages, давайте убедимся, что ваш Nuxt-проект готов к развертыванию в режиме статического сайта.

Настройка Nuxt для вывода статики

Вам нужно убедиться, что проект собирается как статический сайт. Для этого проверьте файл nuxt.config.js:

// nuxt.config.js
export default {
  target: "static", // Делаем билд в статическом режиме
  router: {
    base: '/имя-репозитория/' // Указываете здесь имя вашего репозитория на GitHub
  }
}

Развертывание Nuxt-приложения на GitHub — это важный этап в жизненном цикле любого проекта. Правильное развертывание позволяет сделать приложение доступным для пользователей и обеспечивает его надежную работу. Понимание процесса развертывания на GitHub — это ключевой навык для любого Nuxt-разработчика. Если вы хотите детальнее погрузиться в мир Nuxt, освоить все его тонкости и стать настоящим профессионалом — приходите на наш большой курс Nuxt - fullstack Vue фреймворк. На курсе 129 уроков и 13 упражнений, AI-тренажеры для безлимитной практики с кодом и задачами 24/7, решение задач с живым ревью наставника, еженедельные встречи с менторами.

Пояснение:
Свойство target: "static" говорит Nuxt выводить статику, а настройка router.base критична для корректной работы роутинга на GitHub Pages, который публикует сайт в подпапке /имя-репозитория/.

Как выбрать base

Допустим, ваш репозиторий называется my-nuxt-app, укажите:

  router: {
    base: '/my-nuxt-app/'
  }

Если ваш сайт должен работать в корне домена (например, вы разворачиваете в репозитории username.github.io), то router.base указывать не нужно.

Установка зависимостей

Убедитесь, что у вас актуальные зависимости, и у вас прописаны нужные скрипты для билда и генерации:

"scripts": {
  "dev": "nuxt",
  "build": "nuxt build",
  "generate": "nuxt generate",
  "start": "nuxt start"
}

Для генерации статического билда вам нужен скрипт "generate". Если его нет — добавьте.

Создание и настройка репозитория

Для деплоя на GitHub Pages проект должен быть загружен в репозиторий на GitHub.

1. Создайте новый репозиторий на GitHub.
2. Склонируйте его себе на компьютер или инициализируйте git в папке проекта:

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/ваш-логин/имя-репозитория.git
git push -u origin master

Совет:
Лучше использовать основной стандартный бранч: main или master (актуально для вашего репозитория).

Теперь продолжим с организацией публикации билда.

Сборка и деплой Nuxt-приложения на GitHub Pages

Самый простой, автоматизированный и современный способ деплоя — использовать GitHub Actions. Ниже я описываю под шагам, как это реализовать.

Шаг 1. Подготовьте workflow для деплоя

Создайте директорию .github/workflows и файл, например, deploy.yml:

.github/
└── workflows/
    └── deploy.yml

Шаг 2. Настройте деплой скрипт

Вот пример рабочего GitHub Actions workflow:

name: Deploy Nuxt App to GitHub Pages

on:
  push:
    branches:
      - main # Обновляйте, если у вас другой основной бранч

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Install Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18 # Можно выбрать актуальную версию

      - name: Install dependencies
        run: npm install

      - name: Generate static site
        run: npm run generate

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist
          # Если нужен custom domain, добавьте здесь extra параметры

Объяснения к steps

• actions/checkout@v3 — получает ваш код из репозитория.
• actions/setup-node@v3 — инициализирует Node.js окружение.
• npm install — ставит npm-зависимости.
• npm run generate — собирает проект в статику (результат будет в папке dist).
• peaceiris/actions-gh-pages@v3 — публикует содержимое папки dist на вашу ветку gh-pages, которую использует GitHub Pages.

Шаг 3. Включите GitHub Pages в настройках репозитория

После первого успешного workflow вам нужно:

• Перейти в настройки репозитория на GitHub (Settings).
• Найти раздел Pages.
• В Source выбрать ветку gh-pages. Обычно путь указывается / (root) — если используете стандартный workflow.

GitHub сам подхватит содержимое ветки gh-pages и начнет раздавать сайт.

Шаг 4. Проверьте деплой

Обычно сайт становится доступен по ссылке:

https://ваш-логин.github.io/имя-репозитория/

Время активации — от пары минут до 10-15 минут.

Корректировка ссылок и роутинга

Иногда на GitHub Pages статичные сайты открываются с некорректными путями или возникает ошибка с роутингом. Если что-то не работает:

1. Убедитесь, что правильно указан router.base.
2. Проверьте, что опубликованный сайт обращается к ресурсам по относительному адресу.

Персональный домен и HTTPS

Если вы хотите развернуть приложение на своем домене, можно добавить файл CNAME со своим доменом в корень папки dist (или прописать параметр cname в peaceiris/actions-gh-pages).

Пример:

with:
  github_token: ${{ secrets.GITHUB_TOKEN }}
  publish_dir: ./dist
  cname: mydomain.com # ваш домен без https://

Настройте DNS вашего домена на делегирование к GitHub Pages — добавьте запись CNAME со значением ваш-логин.github.io.

GitHub Pages автоматически предоставляет HTTPS к вашему домену через Let's Encrypt.

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

404 Not Found на страницах кроме главной

• Проверьте настройку router.base.
• Убедитесь, что используете только валидный динамический роутинг (для статической сборки нужны pre-generated routes).
• При необходимости настройте fallback (см. ниже).

Пустой экран или не грузятся assets

• Проверьте, что ресурсы подключаются по относительным путям (router.base справляется с этим).
• Откройте DevTools браузера и убедитесь, что все JS/CSS грузятся корректно.

Ссылки открывают страницы с перезагрузкой

GitHub Pages не поддерживает server-side routing — все страницы должны быть статически сгенерированы. SPA-режим и динамические страницы требуют либо генерации всех роутов, либо отдельного index.html для fallback:

Добавьте в Nuxt:

export default {
  generate: {
    fallback: true // будет создан 404.html для client side navigation
  }
}

Альтернативные способы публикации

Хотя самый популярный способ — это через GitHub Actions + peaceiris/actions-gh-pages, вы также можете:

• Собрать билд локально (npm run generate), затем залить dist вручную в ветку gh-pages.
• Использовать сторонние CLI для деплоя, как gh-pages:

npm install --save-dev gh-pages
npm run generate
npx gh-pages -d dist

Это подойдет, если ваш проект маленький и не нужен CI.

Готовая структура проекта

Ваша структура после настройки будет примерно такой:

my-nuxt-app/
├── .github/
│   └── workflows/
│       └── deploy.yml
├── nuxt.config.js
├── package.json
├── pages/
│   └── index.vue
...

Заключение

Вы можете смело использовать Nuxt для публикации современных Vue-приложений на GitHub Pages. Если настроите router.base, убедитесь в корректной генерации статики и добавьте автоматизированный деплой через GitHub Actions — все последующие публикации происходят в одно нажатие. Этот подход идеально подходит для Open Source-документации, портфолио-разработок, одностраничников и небольших демо.

Развертывание на GitHub — это лишь один из способов сделать ваше Nuxt-приложение доступным. Существуют и другие платформы и инструменты, которые могут быть более подходящими для конкретных задач. На курсе Nuxt - fullstack Vue фреймворк вы научитесь не только развертывать приложения на GitHub, но и выбирать оптимальную платформу для развертывания в зависимости от требований проекта. В первых 3 модулях уже доступно бесплатное содержание — начните погружаться в мир Nuxt прямо сегодня.

Частозадаваемые технические вопросы по теме статьи и ответы на них

Как собрать Nuxt, если у меня TypeScript или сторонние плагины?

Если ваш проект использует TypeScript или дополнительные плагины (например, Vuetify, PWA-модуль), никаких принципиальных изменений в деплой workflow нет. Главное — убедитесь, что все зависимости корректно устанавливаются через npm install, а скрипт генерации (npm run generate) прописан правильно.

Какой node-version лучше указывать для Actions?

Используйте свежую LTS-версию Node.js, рекомендую синхронизировать версию с вашей локальной разработкой. Обычно это 18.x или 20.x. Указать можно так:

uses: actions/setup-node@v3
with:
  node-version: 18

Сайт работает только на главной странице, остальные — 404. Как это корректно решать?

Причина — статичная сборка не создает страницы для динамических роутов (например, /blog/1). Чтобы их задеплоить, перечислите заранее все нужные маршруты в nuxt.config.js:

generate: {
  routes: ['/blog/1', '/blog/2'] // Укажите все динамические маршруты, которые нужны
}

Также помогает генерация fallback (как описано выше).

Как очистить старые файлы после деплоя?

peaceiris/actions-gh-pages@v3 по умолчанию перезаписывает ветку gh-pages, удаляя лишнее. Если вручную деплоите, предварительно удаляйте старое содержимое.

Как деплоить несколько приложений на разные подпапки одного сайта?

Нужно публиковать сборки с разной настройкой router.base, а в каждом репозитории использовать уникальный путь. GitHub Pages по умолчанию публикует только один каталог, так что решение — создать отдельные репозитории для каждого приложения либо аккуратно собирать их итоговые файлы и выкладывать в нужные вложенные папки руками.