Развертывание гибридных веб-сайтов Next.js на Статические веб-приложения Azure (предварительная версия)

Статья
03/18/2024

В этом руководстве вы узнаете, как развернуть веб-сайт Next.js для Статические веб-приложения Azure, используя поддержку Next.js функций, таких как компоненты сервера React, серверная отрисовка (SSR) и маршруты API.

Примечание.

Next.js гибридная поддержка доступна в предварительной версии.

Необходимые компоненты

Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
Учетная запись GitHub. Создайте учетную запись бесплатно .
Установленный компонент Node.js.
Next.js установлен интерфейс командной строки . Дополнительные сведения см. в руководстве по началу работы с Next.js.

Неподдерживаемые функции в предварительной версии

Следующие функции Статические веб-приложения не поддерживаются для Next.js с гибридной отрисовкой:

Связанные API с помощью Функции Azure, службы приложение Azure, приложений контейнеров Azure или Azure Управление API.
Локальная эмуляция и развертывание SWA CLI.
Частичная поддержка staticwebapp.config.json файла.
- Резервный вариант навигации не поддерживается.
- Перезаписи маршрутов в приложении Next.js должны быть настроены в next.config.jsпределах .
- Конфигурация в staticwebapp.config.json файле имеет приоритет над конфигурацией внутри next.config.js.
- Настройка сайта Next.js должна обрабатываться с помощью next.config.js полной совместимости функций.
skip_app_build и skip_api_build не может использоваться в образе Azure/static-web-apps-deploy@v1 развертывания.
Добавочное статическое восстановление (ISR) не поддерживает кэширование изображений.

Примечание.

Максимальный размер приложения для гибридного приложения Next.js составляет 250 МБ. Используйте автономную функцию, Next.js для оптимизированных размеров приложений. Если это недостаточно, рассмотрите возможность использования статического HTML-файла, экспортированного Next.js, если размер приложения превышает 250 МБ.

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

В этой статье для простоты используются шаблон из репозитория GitHub. Шаблон содержит начальное приложение для развертывания в Статические веб-приложения Azure.

Перейдите к следующему расположению, чтобы создать новый репозиторий.

https://github.com/staticwebdev/nextjs-hybrid-starter/generate
Присвойте репозиторию имя my-first-static-web-app
Щелкните Create repository from template (Создание репозитория из шаблона).

Создание Статического веб-приложения

Теперь, когда репозиторий создан, можно создать статическое веб-приложение на портале Azure.

Переход на портал Azure.
Выберите Создать ресурс.
Выполните поиск по запросу Статические веб-приложения.
Выберите Статические веб-приложения.
Нажмите кнопку создания.

В разделе Основные сведения настройте новое приложение и свяжите его с репозиторием GitHub.

Снимок экрана: раздел

Параметр	Значение
Отток подписок	Выберите свою подписку Azure.
Группа ресурсов	Выберите ссылку "Создать" и введите статические веб-приложения-test в текстовом поле.
Имя.	В текстовом поле введите my-first-static-web-app .
Тип плана	Выберите Бесплатно.
Функции Azure и сведения о промежуточном хранении	Выберите ближайший к вам регион.
Оригинал	Выберите GitHub.

Выберите вход с помощью GitHub и выполните проверку подлинности с помощью GitHub .

После входа с помощью GitHub введите сведения о репозитории.

Параметр	Значение
Организация	Выберите свою организацию.
Репозиторий	Выберите my-first-web-static-app.
Ветвь	Выберите Main.

Снимок экрана: сведения о репозитории в портал Azure.

Примечание.

Если репозитории не отображаются:

Возможно, вам потребуется авторизовать Статические веб-приложения Azure в GitHub. Перейдите к репозиторию GitHub и перейдите к Параметры приложениям>, авторизованным Приложение OAuth>, выберите Статические веб-приложения Azure и выберите "Предоставить".
Возможно, вам потребуется авторизовать Статические веб-приложения Azure в организации Azure DevOps. Чтобы предоставить разрешения, необходимо быть владельцем организации. Запрос доступа к сторонним приложениям через OAuth. Дополнительные сведения см. в разделе "Авторизация доступа к REST API" с помощью OAuth 2.0.

В разделе Сведения о сборке добавьте сведения о конфигурации, относящиеся к предпочитаемой интерфейсной платформе.

Выберите Next.js в раскрывающемся списке предустановок сборки.
Оставьте в поле Расположение приложения значение по умолчанию.
Оставьте поле Расположение API пустым.
Оставьте поле Расположение артефакта приложения пустым.

Выберите Review + create (Просмотреть и создать).

Снимок экрана: кнопка создания.

Просмотр веб-сайта

При развертывании статического приложения следует учитывать два фактора. Сначала создаются базовые ресурсы Azure, составляющие приложение. Второй — это рабочий процесс, который создает и публикует приложение.

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

В окне обзора Статические веб-приложения отображается ряд ссылок, которые помогают взаимодействовать с веб-приложением.

Снимок экрана: окно обзора Статические веб-приложения Azure.

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

Когда рабочий процесс GitHub Actions завершится, щелкните ссылку на URL-адрес, чтобы открыть веб-сайт на новой вкладке.

Настройка проекта Next.js локально для внесения изменений

Клонируйте новый репозиторий на компьютер. Обязательно замените <YOUR_GITHUB_ACCOUNT_NAME> именем учетной записи.
```
git clone http://github.com/<YOUR_GITHUB_ACCOUNT_NAME>/my-first-static-web-app
```
Откройте проект в Visual Studio Code или предпочитаемом редакторе кода.

Добавление отрисованных на сервере данных с помощью компонента сервера

Чтобы добавить отрисованные сервером данные в проект Next.js с помощью маршрутизатора приложений, измените компонент Next.js, чтобы добавить серверные операции для отрисовки данных в компоненте. По умолчанию Next.js компоненты — это серверные компоненты, которые могут быть отрисованы на сервере.

app/page.tsx Откройте файл и добавьте операцию, которая задает значение переменной, вычисляемой на стороне сервера. Примеры включают получение данных или других операций сервера.
```
export default function Home() {
    const timeOnServer = new Date().toLocaleTimeString('en-US');
    return(
        ...
    );
}
```
next/cache Импортируйте и вызовите unstable_noStore его в компонентеHome, чтобы обеспечить динамическое отображение маршрута.
```
import { unstable_noStore as noStore } from 'next/cache';

export default function Home() {
    noStore();

    const timeOnServer = new Date().toLocaleTimeString('en-US');
    return(
        ...
    );
}
```
Примечание.

Этот пример заставляет динамическую отрисовку этого компонента продемонстрировать отрисовку сервера текущего времени. Модель маршрутизатора приложений Next.js рекомендует кэширование отдельных запросов данных для оптимизации производительности приложения Next.js. Дополнительные сведения о выборке и кэшировании данных см. в Next.js.

Home Обновите компонент в app/pages.tsx, чтобы отобразить данные на стороне сервера.

import { unstable_noStore as noStore } from 'next/cache';

export default function Home() {
    noStore();

    const timeOnServer = new Date().toLocaleTimeString('en-US');
    return(
        <main className="flex min-h-screen flex-col items-center justify-between p-24">
            <div>
                This is a Next.js application hosted on Azure Static Web Apps with 
                hybrid rendering. The time on the server is <strong>{timeOnServer}</strong>.
            </div>
        </main>
    );
}

Добавление маршрута API

Помимо компонентов сервера Next.js предоставляет обработчики маршрутов, которые можно использовать для создания маршрутов API в приложение Next.js. Эти API можно получить в клиентских компонентах.

Начните с добавления маршрута API.

Создайте файл по адресу app/api/currentTime/route.tsx. Этот файл содержит обработчик маршрутов для новой конечной точки API.

Добавьте функцию обработчика для возврата данных из API.

import { NextResponse } from 'next/server';

export const dynamic = 'force-dynamic';

export async function GET() { 
    const currentTime = new Date().toLocaleTimeString('en-US');

    return NextResponse.json({ 
        message: `Hello from the API! The current time is ${currentTime}.`
    });
}

Создайте файл по адресу app/components/CurrentTimeFromAPI.tsx. Этот компонент создает контейнер для клиентского компонента, который извлекает API из браузера.

Добавьте клиентский компонент, который извлекает API в этом файле.

'use client';

import { useEffect, useState } from 'react';

export function CurrentTimeFromAPI(){
    const [apiResponse, setApiResponse] = useState('');
    const [loading, setLoading] = useState(true);

    useEffect(() => {
        fetch('/api/currentTime')
            .then((res) => res.json())
            .then((data) => {
            setApiResponse(data.message);
            setLoading(false);
            });
        }, 
    []);

    return (
        <div className='pt-4'>
            The message from the API is: <strong>{apiResponse}</strong>
        </div>
    )
}

Этот клиентский useEffect компонент получает API с помощью перехватчика React для отрисовки компонента после завершения загрузки. Директива 'use client' определяет этот элемент как компонент клиента. Дополнительные сведения см. в разделе "Компоненты клиента".

Измените приложение/page.tsx для импорта и отрисовки клиентского CurrentTimeFromAPI компонента.

import { unstable_noStore as noStore } from 'next/cache';
import { CurrentTimeFromAPI } from './components/CurrentTimeFromAPI';

export default function Home() {
    noStore();

    const timeOnServer = new Date().toLocaleTimeString('en-US');
    return(
        <main className="flex min-h-screen flex-col items-center justify-between p-24">
            <div>
                This is a Next.js application hosted on Azure Static Web Apps with 
                hybrid rendering. The time on the server is <strong>{timeOnServer}</strong>.
            </div>
            <CurrentTimeFromAPI />
        </main>
    );
}

Результат маршрута API отображается на странице.

Снимок экрана: отображение выходных данных из маршрута API.

Настройка версии среды выполнения для Next.js

Для некоторых версий Next.js требуются определенные версии Node.js. Чтобы настроить определенную версию узла, можно задать свойство "engines" файла package.json , чтобы назначить версию.

{
  ...
  "engines": {
    "node": "18.17.1"
  }
}

Задание переменных среды для Next.js

Next.js использует переменные среды во время сборки и во время запроса для поддержки статического создания страниц и динамического создания страниц с помощью отрисовки на стороне сервера. Поэтому задайте переменные среды как в задаче сборки, так и в переменных среды Статические веб-приложения Azure ресурса.

...
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
          action: "upload"
          app_location: "/" 
          api_location: ""
          output_location: "" 
        env:
          DB_HOST: ${{ secrets.DB_HOST }}
          DB_USER: ${{ secrets.DB_USER }}
          DB_DATABASE: ${{ secrets.DB_DATABASE }}
          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
          DB_PORT: ${{ secrets.DB_PORT }}
...

Включение автономной функции

Если размер приложения превышает 250 Мб, функция трассировки выходных файлов Next.js помогает оптимизировать размер приложения и повысить производительность.

Трассировка выходных файлов создает сжатые версии всего приложения с необходимыми зависимостями пакета, встроенными в папку с именем next/standalone. Эта папка предназначена для самостоятельного развертывания без дополнительных node_modules зависимостей.

Чтобы включить функцию standalone , добавьте в ваше приложение next.config.jsследующее дополнительное свойство:

module.exports ={
    output:"standalone",
}

Для копирования статических файлов в автономные выходные данные также необходимо настроить build команду в package.json файле.

{
  ...
  "scripts": {
    ...
    "build": "next build && cp -r .next/static .next/standalone/.next/ && cp -r public .next/standalone/"
    ...
  }
  ...
}

Настройка маршрутизации Next.js и ПО промежуточного слоя для развертывания Статические веб-приложения Azure

Проект Next.js можно настроить для пользовательской обработки маршрутов с перенаправлениями, перезаписями и ПО промежуточного слоя. Эти обработчики обычно используются для проверки подлинности, персонализации, маршрутизации и интернационализации. Настраиваемая обработка влияет на маршрутизацию Next.js сайта по умолчанию, а конфигурация должна быть совместима с размещением на Статические веб-приложения.

Статические веб-приложения проверяет успешность развертывания сайта Next.js путем добавления страницы на сайт во время сборки. Страница называется public/.swa/health.htmlи Статические веб-приложения проверяет успешное запуск и развертывание сайта, перейдя к /.swa/health.html сайту и убедившись в успешном ответе. ПО промежуточного /.swa/health.html слоя и настраиваемая маршрутизация, которая включает перенаправления и перезаписи, может повлиять на доступ к пути, что может предотвратить проверку развертывания Статические веб-приложения. Чтобы настроить ПО промежуточного слоя и маршрутизацию для успешного развертывания в Статические веб-приложения, выполните следующие действия.

Исключите маршруты, начиная с .swa файла (или.js) в middleware.ts конфигурации ПО промежуточного слоя.

export const config = {
  matcher: [
    /*
     * Match all request paths except for the ones starting with:
     * - .swa (Azure Static Web Apps)
     */
    '/((?!.swa).*)',
  ],
}

Настройка перенаправлений для next.config.js исключения маршрутов, начиная с .swa

module.exports = {
    async redirects() {
        return [
          {
            source: '/((?!.swa).*)<YOUR MATCHING RULE>',
            destination: '<YOUR REDIRECT RULE>', 
            permanent: false,
          },
        ]
    },
};

Настройте перезаписи, next.config.js чтобы исключить маршруты, начиная с .swa

module.exports = {
    async rewrites() {
        return {
            beforeFiles: [
                {
                    source: '/((?!.swa).*)<YOUR MATCHING RULE>',
                    destination: '<YOUR REWRITE RULE>', 
                }
            ]
        }
    },
};

Эти фрагменты кода исключают пути, которые начинаются с .swa обработки пользовательской маршрутизацией или ПО промежуточного слоя. Эти правила гарантируют, что пути разрешаются должным образом во время проверки развертывания.

Включение ведения журнала для Next.js

Следуя рекомендациям по устранению неполадок с API сервера Next.js, добавьте ведение журнала в API для перехвата этих ошибок. Ведение журнала в Azure использует Аналитика приложения. Чтобы предварительно загрузить этот пакет SDK, необходимо создать пользовательский скрипт запуска. Чтобы получить дополнительные сведения, обратитесь к разделу

Очистка ресурсов

Если вы не собираетесь использовать это приложение в дальнейшем, вы можете удалить экземпляр службы "Статические веб-приложения Azure", выполнив следующие действия:

Откройте портал Azure.
Выполните поиск my-first-web-static-app с помощью верхней строки поиска.
Выберите имя приложения.
Выберите команду Удалить.
Нажмите кнопку Да, чтобы подтвердить действие удаления (это действие может занять несколько секунд).

Следующие шаги

Настройка параметров приложения

Развертывание гибридных веб-сайтов Next.js на Статические веб-приложения Azure (предварительная версия)

Необходимые компоненты

Неподдерживаемые функции в предварительной версии

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

Создание Статического веб-приложения

Просмотр веб-сайта

Настройка проекта Next.js локально для внесения изменений

Добавление отрисованных на сервере данных с помощью компонента сервера

Добавление маршрута API

Настройка версии среды выполнения для Next.js

Задание переменных среды для Next.js

Включение автономной функции

Настройка маршрутизации Next.js и ПО промежуточного слоя для развертывания Статические веб-приложения Azure

Включение ведения журнала для Next.js

Очистка ресурсов

Следующие шаги

Дополнительные ресурсы