Astro: статический выпуск и передача сборки

Финальное состояние «Полки» содержит Markdown, общую оболочку, каталог, поиск, последовательность и карту. Теперь опишем, что потребуется для подготовки переносимого статического выпуска. Саму сборку и публикацию в этом уроке не выполняем. Результат — договор передачи, в котором различаются исходники, производные файлы, адреса и условия сервера.

RELEASE.md перечисляет закреплённые зависимости и команды будущей работы. После разрешённой установки нужно сохранить lockfile. Он уточнит фактический граф зависимостей, а не только верхнеуровневые версии package.json. В архиве серии lockfile не выдуман: зависимости не устанавливались. Такое ограничение важнее ложного ощущения, что окружение уже полностью воспроизведено.

Выпуск как согласованный набор файлов

В статическом выпуске хостингу передаётся содержимое dist, а не исходные Markdown, src или node_modules. Node нужен для подготовки, но не обязательно для выдачи готовых файлов. Однако сохранённый .php путь требует отдельного поведения веб-сервера. Обычный static preview не является подтверждением такого производственного договора.

Конфигурация публичного профиля должна использовать настоящий домен. Перед сборкой заменяются polka.example и связанные указания robots. Флаг POLKA_PUBLIC_BUILD=true влияет на индексирование и карту, но не превращает пример в опубликованный сайт. Не оставляйте его единственным признаком готовности: правильная среда, набор URL и настройки хостинга должны быть согласованы отдельно.

Postbuild переносит один временный HTML в сохранённый публичный путь. Выпуск должен содержать этот результат вместе с каталогом и индексом, уже ссылающимися на него. Нельзя загружать только статьи, оставив старый поиск и карту, или смешивать каталоги разных выпусков. Пользователь тогда получит разные версии данных в зависимости от выбранного маршрута.

Перед заменой существующего сайта следует сохранить копию файлов и настроек сервера. Архив HTML без правил выдачи PHP-путей может быть недостаточен для восстановления. Возврат должен вернуть прежний согласованный выпуск и его маршрутизацию. В учебном проекте автоматический откат не реализован, поэтому не описываем его как уже готовую кнопку.

План будущего рассмотрения включает прямые запросы к каждому публичному адресу, правильный Content-Type, canonical, переходы из каталога, границы пагинации и состав карты. Список ожидаемых URL формируется из выбранных записей. Для ProfessorWeb фактический защищённый реестр значительно шире маленького набора «Полки», и его нельзя заменить пятью демонстрационными адресами.

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

Ожидаемая итоговая система позволяет добавлять Markdown-уроки, изменять общий шаблон и сохранять договорённые пути без ручной переписи каждого списка. При подготовке не выполнялись установка, учебная сборка, браузерные сценарии, тесты и деплой. Архив передаёт исходники четырнадцати этапов и план будущих действий. Его границы нужно сохранять при передаче следующему автору, чтобы ожидаемый результат не превратился в неподтверждённое утверждение.

Полный файл package.json текущего этапа:

{
  "name": "polka-content-lab",
  "private": true,
  "type": "module",
  "engines": {
    "node": ">=22.12.0"
  },
  "scripts": {
    "dev": "astro dev --host 127.0.0.1",
    "build": "astro build && node scripts/preserve-urls.mjs",
    "preview": "astro preview --host 127.0.0.1"
  },
  "dependencies": {
    "astro": "7.3.8",
    "@astrojs/sitemap": "3.7.4"
  }
}

Полный файл RELEASE.md текущего этапа:

# Передача статического выпуска

Это инструкция для будущего действия, не выполненный релиз. Никаких зависимостей, сборок, HTTP-проверок или публикации при написании серии не выполнялось.

Среда: Node >=22.12.0, Astro 7.3.8, @astrojs/sitemap 3.7.4. lockfile появится после разрешённой установки и подлежит хранению рядом с package.json.

Локальный выпуск: npm install; npm run build; npm run preview. Производственный профиль требует POLKA_PUBLIC_BUILD=true и замены домена polka.example. preview — средство локального просмотра, не договор сервера о .php.

Содержимое dist переносится отдельно от src и node_modules. До замены старого выпуска сохраните архив файлов и настройки веб-сервера. Адрес /my/content/intro.php должен возвращать HTML и корректный canonical. Временный /articles/markdown.html отсутствует. Сверьте полный список URL, статусы и внутренние ссылки в реальной среде.

legacy-paths.json дублирует publicPath специально для sitemap; при изменении старого пути обновляются оба. Для крупного проекта замените ручной реестр единым исходным manifest, выдающим обе формы. В этой учебной серии преобразование намеренно показано явно.

Автоматический откат не реализован. Возврат включает предыдущий dist, настройки маршрутов и robots. Не смешивайте файлы разных выпусков.

Разбор состояния библиотеки

Для передачи полезно различать архив исходников серии и резервную копию действующего сайта. Первый содержит учебные состояния, второй должен сохранять настоящий опубликованный выпуск и настройки. Нельзя восстановить ProfessorWeb из маленькой Полки, даже если оба проекта используют Markdown. Сходство архитектуры не означает одинаковый реестр страниц, ресурсы и договоры хостинга.

Согласованный выпуск желательно готовить отдельно от текущего production-каталога. Преобразование старых путей и генерация индекса могут завершиться не одновременно. Если менять действующую папку во время подготовки, посетитель получит промежуточные состояния. Способ атомарной замены зависит от хостинга и требует отдельной инструкции. Урок определяет потребность, но не выдаёт универсальную команду для любого сервера.

Перед реальной передачей также нужно исключить приватные заметки, временные manifest и файлы локальной среды. Наш postbuild удаляет url-map после использования, но это не полный аудит всех возможных ресурсов. Набор dist следует рассмотреть как самостоятельный артефакт. То, что src хорошо организован, не является доказательством отсутствия лишних данных в конечной папке.

Для самостоятельного разбора составьте таблицу четырёх объектов: исходник Markdown, шаблон Base, готовая HTML-страница и правило сервера для PHP-пути. Укажите, какое изменение затрагивает каждый объект и какое действие требуется после него. Такой разбор показывает, почему исправление текста, смена общего дизайна и изменение маршрутизации имеют разную область влияния, хотя посетитель видит одну страницу.

Восстановление должно быть практической процедурой, которую можно повторить. Архив без информации о домене, robots и адресных правилах оставляет важные условия неизвестными. Однако проверка восстановления является отдельным исполнением и не проводится в этом локальном заказе. Мы записываем необходимые сведения, не сообщая, что возврат уже испытан. Это делает будущий релиз предметным и уменьшает риск ложной уверенности.

Когда учебная серия будет опубликована, сохраните рядом версии и дату сверки источников. Со временем Astro и интеграции изменятся, а пример останется полезным, если читатель видит его профиль. Обновление всего курса следует начинать со сверки APIs и последовательности полных снимков. Замена одной цифры в package.json без пересмотра маршрутов и адресного преобразования не является полноценной миграцией учебного проекта.

План выпуска не включает команды доступа к действующему хостингу. Он описывает необходимые условия и состав артефакта, чтобы следующий разрешённый шаг был конкретным. Такой подход позволяет заранее увидеть проблему старого расширения и синхронизации карты без изменения production. Запись команд сборки в статье также не означает их исполнение. Фактическое действие должно быть отражено отдельно, когда пользователь разрешит соответствующий этап.

Условия для самостоятельного наблюдения

Это план будущего разбора, а не журнал выполненных проверок. Рассмотрите одинаковые исходные данные и сопоставьте действие с ожидаемым состоянием.

Условие	Ожидаемое состояние и его граница
Передаются исходники	Они предназначены для редакции и сборки, не являются готовым содержимым хостинга.
Передаётся dist	Нужен согласованный результат одного выпуска, включая поиск, карту и старые пути.
Нет lockfile	Среда ещё не установлена, фактический граф зависимостей не считается подтверждённым.
Возврат старого выпуска	Восстанавливаются файлы и необходимые правила сервера, а не одна главная страница.
Главная открылась	Это не подтверждает прямую выдачу всех защищённых исторических адресов.
Нужно подтвердить трафик	Потребуется наблюдение после разрешённой публикации; сейчас такого результата нет.

Оглавление серии, курсы ProfessorWeb и полный архив исходников. Для этого урока выберите lesson-14.

Первичные источники: Build, Configuration.

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