Локальная сборка сайта перед публикацией

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

Что проверить до отправки на сервер

Проверьте версию среды, установите зависимости командой npm ci, запустите тесты и production build, указанные в package.json. Осмотрите созданный каталог: обязательные страницы и ресурсы должны существовать, а .env, .git, ключей и внутренних конфигураций там быть не должно. Запустите локальный preview, проверьте несколько маршрутов и только затем передавайте артефакт.

Зафиксируйте исходную версию проекта

В корне репозитория выполните три команды только для чтения. Они покажут незаписанные изменения, имя текущей ветки и короткий идентификатор последней зафиксированной версии:

git status --short
git branch --show-current
git rev-parse --short HEAD

Перед сборкой состав будущего релиза должен быть понятен по git status и diff. Незакоммиченный файл не всегда является ошибкой во время разработки, но он не должен незаметно потеряться или смешаться с чужим изменением.

Проверьте версии инструментов:

node --version
npm --version

Сверяйте поддерживаемую версию с документацией проекта, полем engines или README. Не выполняйте major-upgrade Node.js, сборщика или фреймворка непосредственно перед публикацией без отдельного теста.

Установите зависимости воспроизводимо

npm ci

Команда ожидает согласованный package-lock.json, очищает существующий каталог зависимостей node_modules и устанавливает зафиксированное дерево. Ошибка расхождения с package.json показывает, что описание и точные версии расходятся: исправьте их локально, а не обходите проверку на сервере.

Установочные сценарии npm выполняют код зависимостей. Не запускайте их с root. Просмотрите неожиданное изменение пакетов и источник зависимости до публикации. Автоматический npm audit fix --force тоже не является безопасной универсальной командой: он способен поменять major-версии и сломать сборку.

Запустите проверки и соберите готовый каталог

Названия сценариев берите из package.json и README. Для многих npm-проектов последовательность выглядит так:

npm run check
npm run build

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

Прочитайте отчёт сборки

Обратите внимание на:

• количество созданных маршрутов;
• отсутствующие или дублирующиеся slug;
• ошибки импорта изображений;
• предупреждения о контенте;
• место итогового каталога;
• длительность, если она резко изменилась;
• итог проверки готового артефакта.

Каталог результата, то есть артефакт сборки, может называться dist, build, out или иначе. Возьмите путь из конфигурации сборщика и сохраните его в переменной для следующих команд; не угадывайте по примеру из другой технологии.

Проверьте обязательные файлы

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

$artifactDir = 'build'
$required = @(
  "$artifactDir/index.html",
  "$artifactDir/404.html",
  "$artifactDir/assets/app.css"
)
$required | ForEach-Object {
  if (-not (Test-Path -LiteralPath $_)) { throw "Нет файла: $_" }
}

В Linux shell та же проверка выполняется через test -f. Здесь также замените build и перечень файлов на значения своего проекта:

artifact_dir="build"
test -f "$artifact_dir/index.html"
test -f "$artifact_dir/404.html"
test -f "$artifact_dir/assets/app.css"

Список должен отражать реальные критичные маршруты и ресурсы приложения. Такая проверка ловит ситуацию, когда build завершился успешно технически, но потерял обязательную страницу или основной stylesheet.

Исключите секреты и внутренние файлы

На Linux или macOS просмотрите все имена в готовом каталоге и отдельно найдите типичные секретные файлы. Команды ничего не удаляют; второй вывод должен остаться пустым:

find build -type f | sort
find build -type f \( -name '.env*' -o -name '.git*' -o -name '*.key' -o -name '*.pem' \)

Вторая команда не должна находить приватные данные. Дополнительно ищите тестовый маркер, а не настоящий пароль. Не вставляйте secret в командную строку или отчёт CI ради поиска — он попадёт в историю и журнал.

Проверьте общий размер и самые крупные файлы:

du -sh build
find build -type f -printf '%s %p\n' | sort -nr | head

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

Проверьте ссылки и метаданные

Build способен создать страницу с битой внутренней ссылкой: строка URL не всегда проверяется сборщиком. Добавьте обход внутренних ссылок по готовому каталогу. Для HTML также полезно контролировать уникальность title и description, один H1 и корректный канонический адрес.

Не исправляйте внешний URL автоматически по первому редиректу: он может вести на страницу входа, географическую заглушку или временную ошибку. Для внутренних ссылок итоговая сборка остаётся надёжным источником истины.

При передаче готового архива полезно вычислить контрольную сумму и сохранить её рядом с release ID. Это подтверждает, что на сервер попал тот же артефакт, который прошёл локальную проверку.

Откройте именно собранную версию

npm run preview

Откройте адрес, который показала команда. Проверьте:

• главную и минимум одну вложенную страницу;
• список, пагинацию и 404;
• CSS, JavaScript, изображения и favicon;
• ссылки с завершающим слешем и без него, если это важно;
• светлую/тёмную тему и базовую мобильную ширину;
• отсутствие ошибок в консоли браузера.

Команда preview должна обслуживать готовый артефакт, а не исходники в режиме разработки. Сервер разработки может на лету создать маршрут, которого нет в итоговом каталоге.

Выполните HTTP-проверку локально

curl --fail --silent --show-error --head http://localhost:4321/
curl --fail --silent --show-error http://localhost:4321/robots.txt
curl --fail --silent --show-error http://localhost:4321/404-does-not-exist

Последняя команда ожидаемо должна завершиться ошибкой при корректном 404. Проверяйте не только тело, но и HTTP-код. Если preview использует другой порт, подставьте фактический адрес.

Проверьте воспроизводимость

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

Если build зависит от локального файла, которого нет в Git и который не передаётся как документированная конфигурация, будущий deploy ненадёжен. Добавьте явную проверку обязательного входа.

Частые ошибки

• Проверяют dev-сервер, но не выполняют production build.
• Используют npm install, незаметно меняют lock-файл и публикуют другое дерево.
• Копируют весь проект вместо готового артефакта.
• Не проверяют вложенные маршруты и 404.
• Игнорируют предупреждения сборщика.
• Запускают установку зависимостей с root.
• Считают локальный preview доказательством работы DNS и HTTPS.

Перед передачей артефакта проверьте состав изменения в Git и контрольную сумму. Порядок копирования и переключения версии описан в руководстве по ручной публикации.

Источники

• npm ci — npm Docs
• npm run-script — npm Docs
• curl exit codes — curl documentation