Руководство 8: опубликовать блог на своём домене
Подготовьте полный статический сайт, настройте хостинг и домен, проверьте публичные результаты.
На этой странице
Китайские строки в примерах locales.zh сохранены намеренно: они показывают настройку китайского контента без изменения других языков. Китайские и английские значения по умолчанию в таблицах — цитаты из темы, а не пропущенный перевод.
Это руководство 8 из 8. Порядок всех руководств · Справочник настроек.
После локального запуска для публикации нужны три шага: определить окончательный домен, создать полный статический результат и настроить хостинг для выдачи этих файлов по домену. Тема не покупает домен, не меняет DNS и не входит на платформу автоматически.
Текущий starter собирает статический сайт. Постоянно работающий Node.js в production и SSR adapter ради публикации не нужны. Ниже предполагаются npm-проект и стандартный dist/.
1. Определите окончательный адрес
Подготовьте свой домен, например https://blog.example.com. Объедините с верхнеуровневым site в src/site.config.ts:
site: {
url: 'https://blog.example.com',
},
Укажите публичный окончательный адрес, не localhost, URL статьи или панель хостинга. Остальные данные сайта сохраните.
Значение используется для canonical, RSS, sitemap, превью ссылок и публичных ссылок контента. Оно не меняет локальный dev-адрес и не направляет ещё не подключённый домен на сайт автоматически.
Проверьте старые переопределения среды
PUBLIC_SITE_URL в .env, применимых .env.* или среде сборки приоритетнее файла. Если изменение site.url оставляет старый домен, проверьте все эти места. Обычный dev использует development, build — production; с --mode читается и соответствующая конфигурация режима, поэтому одной проверки .env недостаточно.
Удалите ненужную переменную и используйте site.url либо задайте правильное значение в каждой среде. После изменения пересоберите: вручную менять одну ссылку в старых результатах недостаточно.
Размещайте в корне домена
Сейчас тема рассчитана на корень, например https://blog.example.com/. Подпуть вроде https://example.com/my-blog/ требует дополнительной адаптации. Один Astro base не гарантирует работу всех страниц и ресурсов.
Убедитесь, что хостинг поддерживает сайт в корне, index.html каталогов и нормальные вложенные URL. Для GitHub Pages предпочтительны адрес сайта или собственный домен; не считайте инструкции подпути проекта уже поддержанной настройкой темы. См. размещение Astro и руководство соответствующего хостинга.
2. Подготовьте все исходные файлы
Размещайте собственный проект и ветку с настоящим контентом, а не демонстрационные материалы репозитория разработчика темы как личный блог. Нужны настройки проекта, контент, списки зависимостей и ресурсы.
После новых/заменённых локальных обложек и изображений заметок подготовьте варианты локальным dev или doctor и сохраните:
- Статьи, заметки, собственные страницы и
src/site.config.ts. - Оригиналы изображений статей, public-изображения, значки и нужную музыку.
- Весь
src/assets/blog/covers/, включая manifest.json, generated/ и используемые originals/. package.json,package-lock.json, исходные Astro- и hosting-настройки проекта.
Оригиналы могут лежать рядом со статьёй или в public, а не originals: их тоже сохраняйте. Детали — в руководстве изображений.
Dev, build и doctor, включая CI, подготавливают используемые локальные изображения: корректные производные используются повторно, отсутствующие, устаревшие или повреждённые создаются заново. Сохраняйте оригиналы; добавление src/assets/blog/covers/, включая manifest.json и generated/, в Git позволяет повторно использовать результаты без зависимости от кэша хостинга. Отсутствующие или недопустимые оригиналы по-прежнему вызывают ошибку.
Требуется 0.36.2 или новее: Dev, build и doctor (включая CI) повторно используют корректные производные изображения и создают отсутствующие, устаревшие или повреждённые. В версии 0.36.1 перед build/CI сначала подготовьте изображения через dev или prepare-covers. Явная команда prepare-covers --check и синхронизация конфигурации остаются проверками без записи.
Для сборки из Git не нужно коммитить node_modules, .astro или dist: платформа установит зависимости и создаст результат. Не загружайте локальные зависимости как статический сайт. Если env-файлы не в репозитории, задайте нужные переменные на платформе. PUBLIC_ предназначены для открытых данных сайта, а не секретов.
3. Проверьте и откройте настоящую сборку локально
Остановите dev через Ctrl+C, перейдите в корень проекта и выполните:
npm run doctor
npm run preview
По адресу preview проверьте главную, статьи, изображения, меню языков и поиск. Для новых языков и необязательных страниц проверьте входы. Внешним комментариям нужна настоящая браузерная связь: успешная сборка не доказывает правильность удалённых разрешений.
Назначение команд различается:
| Команда | Действие |
|---|---|
npm run dev |
Локальная разработка с подготовкой связанных изображений; без полнотекстового индекса сборки |
npm run doctor |
Локально подготавливает изображения, проверяет Astro и собирает; при включённом About проверяет runtime-настройки |
npm run check |
В текущем starter тоже вызывает doctor; подряд запускать оба не нужно |
npm run build |
Подготавливает или повторно использует производные изображения и собирает сайт |
npm run preview |
Выдаёт существующий dist без новой сборки или публикации |
При любой ошибке сначала исправьте её, не размещайте остатки dist. После успешного doctor результат уже собран: повторять check/build сразу не нужно. Preview останавливается Ctrl+C.
4. Разверните полный статический результат
Можно подключить репозиторий Git для сборки на платформе или загрузить локальный результат. Итог в обоих случаях — одна статическая выдача.
Вариант 1: платформа собирает из Git
Подключите свой репозиторий и настройте:
| Параметр | Текущий starter |
|---|---|
| Ветка сборки | Ваша реальная ветка контента блога |
| Корень проекта | Каталог с package.json блога, не обязательно корень всего репозитория |
| Node.js | Согласно требованиям проекта/зависимостей; starter объявляет 22.12.0 или новее |
| Установка | Для npm — npm ci, нужен сохранённый package-lock.json, соответствующий package.json |
| Команда сборки | npm run build |
| Выходной каталог | dist относительно корня проекта |
Если платформа сама устанавливает зависимости, повторять установку не нужно. Для полного собственного скрипта сначала установите, затем build. Не повторяйте doctor/check/build и не добавляйте генерацию изображений на платформе ради сокрытия несохранённых файлов.
Фреймворк-пресет, ветка и установка зависят от платформы. Выбирайте статическое размещение; npm run dev или npm run preview не являются production-командой запуска.
Вариант 2: загрузите локальную сборку
После успешного doctor загрузите всё содержимое dist/ в корень сайта хостинга. Если выбирается выходная папка — укажите dist; если загружаются файлы — содержимое dist, без дополнительного уровня dist в URL.
Помимо HTML нужны _astro/, _blog-covers/, _social/, поисковый индекс и остальные файлы конкретной сборки. Каталоги с подчёркиванием — не ненужные временные файлы. Один HTML оставит сайт без стилей, скриптов, изображений или поиска.
При повторной публикации используйте полную замену платформы, чтобы не оставлять удалённые статьи, старые страницы и языки. Удаление Markdown локально не удаляет старый HTML ручной загрузки автоматически.
5. Подключите домен на платформе, затем настройте DNS
Добавьте собственный домен на хостинге, затем внесите предложенные им записи в управление DNS домена. Типы и цели записей корня/поддомена могут различаться. Используйте настоящие данные платформы, не пример IP.
Дождитесь подтверждения домена и HTTPS-сертификата, затем откройте окончательный адрес. Если используются голый домен, www и другие, выберите основной, перенаправьте остальные на стороне хостинга и укажите основной в site.url.
canonical — метаданные, не HTTP-перенаправление. site.url темы не управляет DNS, сертификатами и перенаправлениями нескольких доменов: это хостинг и домен. После смены основного адреса обновите старые env-переопределения, пересоберите и разверните.
6. Проверьте страницы и публичные выходы
Откройте прямую ссылку статьи на окончательном домене и обновите страницу. Одного успешного перехода с главной недостаточно для проверки маршрутов. Проверьте изображения, стиль кода, языки и поиск. Функции, проверенные лишь в dev, подтвердите в собранном сайте.
Тема уже подключает эти статические результаты, дублирующие интеграции не нужны:
| Пример адреса | Назначение |
|---|---|
/robots.txt |
Правила обхода и sitemap, не контроль доступа |
/sitemap-index.xml |
Карта сайта с окончательным доменом |
/zh/rss.xml |
Подписка китайских статей; замените zh другим включённым языком |
/llms.txt |
Общий AI-читаемый индекс |
/zh/llms.txt, /zh/llms-full.txt |
Индекс и полный сборник языка при наличии экспортируемого контента |
/zh/blog/my-first-post/index.md |
Markdown публичной статьи; замените slug настоящим |
/zh/fragments/index.md, /zh/about/index.md |
Публичный контент включённых страниц, удовлетворяющих условиям экспорта |
Дата sitemap статьи — updatedDate или pubDate, а не новая выдуманная дата каждой сборки. Отключённые языки/страницы не обязаны иметь экспорт. search: false не делает статью приватной и не запрещает остальные публичные результаты автоматически.
AI-экспорт включает публичные статьи, включённые Fragments и About. Комментарии и декоративные инструменты не входят в основной текст. Настоящие noindex-страницы и страницы с внешним canonical исключаются. Конфликт собственного файла с генерируемым путём останавливает сборку, не перезаписывая его. Экспорты и ссылки обнаружения обновляются при сборке и размещаются вместе.
Эти метаданные и тексты помогают обнаружению и чтению, но не гарантируют индексацию, цитирование AI или рост посещений.
Отличие заголовков хостинга
Сборка дополняет dist/_headers правилом X-Robots-Tag: noindex для /:locale/terminal/*, сохраняя существующие правила и не меняя исходный public/_headers. Поддерживающий формат хостинг применит его; остальным нужны эквивалентные настройки заголовков.
Astro preview не имитирует _headers платформы. Эффект подтверждают ответы настоящего сервиса, а не наличие локального файла. Node-сервер ради этого правила не нужен.
Приоритет домена/среды — в справочнике сайта, поля публичного дополнения — в справочнике GA4 и AI.
7. При необходимости добавьте пояснение для AI-чтения
Для обычной публикации это не нужно. Чтобы описать контекст сайта или дополнительные материалы, объедините на верхнем уровне:
aiReadableContent: {
notes: 'Здесь я описываю свою учёбу; содержание может пересматриваться.',
links: [{ label: 'Страница проекта', href: 'https://example.com/project' }],
},
notes поддерживает Markdown, у links нужны label и href. Используйте публичные HTTP(S)-адреса; корневые/относительные разрешаются от адреса сайта. Это публичное дополнение, не замена текста статьи и не ограничение приватности.
Для языкового переопределения — i18n.locales.<locale>.aiReadableContent. Например, китайское пояснение без ссылок:
i18n: {
locales: {
zh: {
aiReadableContent: {
notes: '中文内容是作者自己的学习笔记。',
links: [],
},
},
},
},
Отсутствующее поле наследует глобальное. notes: ‘’ и links: [] явно скрывают соответствующие части. Дополнение попадает в индексы, сборники и отдельные Markdown: публикуйте только открытые данные и пересобирайте после изменений.
8. При необходимости включите GA4
По умолчанию скрипт Google не загружается. Получите Measurement ID вида G- в веб-потоке Google Analytics; см. инструкцию Google. Принимается только G-ID, не числовой ID ресурса, GTM-контейнер или другой идентификатор.
На верхнем уровне, рядом с site, объедините:
analytics: {
googleAnalyticsId: 'G-XXXXXXXXXX',
},
Замените настоящим ID; пустая строка отключает. Неверный формат вызывает ошибку конфигурации. Одного ID достаточно для всех языков, различаемых путями. Не вставляйте скрипт заново для каждой темы или языка.
Загрузчик выводится только в production-сборке с ID, dev ничего не отправляет. При localhost, его поддоменах и локальных loopback-адресах отправка пропускается. Производственная сборка на LAN IP или удалённом preview-домене может отправлять данные: не все preview исключены.
После размещения откройте окончательный адрес и проверьте realtime GA4. Блокировщики, сеть и настройки статистики могут влиять. Не устанавливайте ту же аналитику повторно вручную, через GTM или другой инжектор. Интерфейс управления согласием не включён; при необходимости подключите его сами.
9. Если размещение не удалось или сайт неверен
| Симптом | Что проверить сначала |
|---|---|
| Ошибка npm ci | Требования Node/зависимостей, наличие package-lock и соответствие package.json |
| missing/stale/modified изображения | Dev, build или doctor восстанавливают производные; при ошибке проверьте оригиналы и пути |
| Сборка успешна, страница 404 | Выходной каталог, ветка, корень, поддержка index и отсутствие неподдержанного подпути |
| Главная работает, обновление статьи даёт 404 | Реальные статические вложенные пути, не размещена ли только главная и не применён ли SPA fallback |
| Нет стилей, изображений или поиска | Полный dist, все ресурсные каталоги, отсутствие переписывания путей |
| canonical/RSS со старым доменом | site.url, PUBLIC_SITE_URL, среда режима и повторные сборка/размещение |
| Настройка онлайн не изменилась | Правильный проект, ветка и последний коммит, а не только локальное редактирование |
| Удалённая статья всё ещё доступна | Старые файлы/кэш размещения, полная замена и кэш хостинга |
| GA4 без данных | Настоящий G-ID, production, нелокальный адрес и отсутствие блокировки скрипта |
Обычный цикл: «локальные изменения и подготовка → проверка/preview → сохранение исходников → сборка/размещение». Обновление темы — в установке, языковые пути — в языках.
Навигация по руководствам и настройкам
Первая публикация завершена. В дальнейшем возвращайтесь к нужному руководству или справочнику.
Назад: другие языки · Все восемь руководств.
Связанные настройки: домен и среда, GA4 и AI-дополнение, ресурсы поиска. Полные пути, значения и ограничения — в общем справочнике.