Описание развёртывания

Сайт документации этого репозитория разворачивается по семейному соглашению на prefix www.lhgb.top (в той же системе, что и четыре сайта android / ios / harmony / windows).

Фреймворк сайта — Astro Starlight (миграция с VitePress выполнена 2026-10-12; об обосновании выбора см. Выбор технологий для сайта документации).

Сборка

pnpm docs:build

Результат сборки — в docs/dist/ (в astro.config.mjs явно задано outDir: 'docs/dist'; это сделано намеренно, чтобы разойтись с корневым dist/ codegen — красная линия 6; каталог добавлен в .gitignore и не попадает в репозиторий).

Все настройки, связанные с развёртыванием, лежат в docs/astro.config.mjs:

Параметр	Значение	Описание
`site`	`https://www.lhgb.top`	Источник сайта для sitemap и SEO
`base`	`/lhui/core/`	Префикс развёртывания; слэши в начале и в конце обязательны
`build.format`	`'file'`	Создаёт `page.html` вместо `page/index.html` — в соответствии с семейным контрактом nginx
`trailingSlash`	`'never'`	Управляется Starlight, в связке с `format: 'file'`

`base` применяется только к тому, что генерируют сами Astro / Starlight: ресурсы страниц, боковая панель, пагинация, переключение языков, sitemap, индекс pagefind. **Следующие два вида не получают автоматический префикс base**:

hero.actions[].link во frontmatter (кнопки CTA на главной странице с template: splash) — Starlight 0.42.6 подставляет это значение как href без изменений, поэтому в index.mdx нужно писать полный префикс целиком, например /lhui/core/guide/quickstart.
Абсолютные ссылки, начинающиеся с /, в тексте markdown — рендерер markdown в Astro 7 не склеивает base.

Ко второму виду этот репозиторий применяет плагин basePrefixPlugin из astro.config.mjs, который на этапе сборки автоматически подставляет префикс, поэтому в тексте можно писать абсолютные пути вида /tokens/reference; первый вид требует ручного написания полного префикса. При изменении base не забудьте синхронно поправить 2 кнопки hero на главной странице.

Загрузка на сервер

Содержимое docs/dist/ загружается в каталог сервера /home/webuser/nginx/lh-ui/core/.

Конфигурация nginx

location ^~ /lhui/core/ {
    alias /home/webuser/nginx/lh-ui/core/;
    index index.html;
    try_files $uri $uri.html $uri/ /lhui/core/index.html;
}

Три семейных контракта, на которых набили шишки (после миграции на Starlight каждый перепроверен и остаётся в силе):

В try_files в fallback обязательно должен быть префикс base (/lhui/core/index.html), иначе при обновлении глубокой ссылки будет 404
Завершающий слэш в alias нельзя опускать; используется в паре с location ^~ /lhui/core/
$uri.html обязателен — при build.format: 'file' этот сайт создаёт файлы вида page.html (URL /lhui/core/page без завершающего слэша), и nginx через $uri.html достаёт реальный файл; без него глубокие ссылки будут отдавать 404

Самопроверка после развёртывания

curl -I https://www.lhgb.top/lhui/core/guide/introduction
grep -c "lhui/core" docs/dist/index.html   # Ожидается > 0
# Обратное утверждение: в артефактах не должно быть внутренних ссылок без base (совпадений должно быть 0)
grep -rcE 'href="/(guide|tokens|specs|cases|codegen|artifacts)/' docs/dist/ | grep -v ':0$' || echo OK

Локальный предпросмотр

pnpm docs:dev        # http://localhost:5185/lhui/core/
pnpm docs:preview    # Предпросмотр продакшен-сборки, также с префиксом base

base в Astro действует и для dev-сервера (в отличие от VitePress, где DOCS_BASE=/ задавался через .env.development), поэтому локальные пути тоже содержат префикс /lhui/core/ — структура URL на локальной машине и на продакшене полностью совпадает, что избавляет от прежней когнитивной нагрузки «локально без префикса, на проде с префиксом».

Распределение портов

Репозиторий	Порт dev	base
lh-ui-vue2	5177	`/lhui/vue2/`
lh-ui-plus	5178	`/lhui/vue3/`
lh-ui-react	5179	`/lhui/react/`
lh-ui-uniapp	5187	`/lhui/uniapp/`
lh-ui-android	5181	`/lhui/android/`
lh-ui-ios	5182	`/lhui/ios/`
lh-ui-harmony	5183	`/lhui/harmony/`
lh-ui-windows	5186	`/lhui/windows/`
lh-ui-core (этот сайт)	5185	`/lhui/core/`

Авторитетный справочник по развёртыванию семейства — 部署/nginx-lhui.conf.md в репозитории lh-ui/docs; эта страница — рабочая заметка самого репозитория. После вступления развёртывания в силу следует синхронно обновить сводную таблицу семейства (текущее изменение не затрагивает другие репозитории).