Next.js build přímo do živého .next — minuty rozbitých stránek při každém deployi

import { Aside } from ‘@astrojs/starlight/components’;

Symptom

Uživatelé náhodně hlásí rozbité stránky (“háže to error”, bílá stránka, 500) — ale když to jdete zkontrolovat, stránka funguje. V error logu:

Error: Cannot find module '/app/.next/server/app/(group)/page.js'
Error: Cannot find module '/app/.next/server/pages/_error.js'

Symptomy korelují s časy nasazení. Čím častěji nasazujete, tím víc stížností.

Root cause

Deploy skript dělal:

git pull && npm run build && pm2 restart app

next build zapisuje přímo do .next, ze kterého běžící instance právě servíruje. Build nejdřív adresář čistí a pak ho minuty plní — celou dobu běžící proces lazy-loaduje moduly stránek z adresáře, který je rozestavěný. Každý deploy = 1–3minutové okno, kdy náhodné stránky padají na “Cannot find module”.

Zákeřné: po dokončení buildu vše funguje, takže při kontrole po deployi problém nenajdete. Trpí jen uživatelé, kteří klikali BĚHEM buildu.

Řešení

1. next.config: distDir řízený proměnnou prostředí:

const nextConfig = {
  distDir: process.env.NEXT_DIST_DIR || ".next",
};

2. Deploy skript builduje bokem a přehodí atomicky až těsně před restartem:

rm -rf .next-build
# přenést cache kvůli rychlosti buildu
[ -d .next/cache ] && mkdir -p .next-build && cp -r .next/cache .next-build/cache

NEXT_DIST_DIR=.next-build npm run build || exit 1   # živý .next nedotčen

rm -rf .next-old
[ -d .next ] && mv .next .next-old
mv .next-build .next        # okno ~ms místo minut
rm -rf .next-old
pm2 restart app

Bonus: při selhání buildu zůstává živý .next netknutý — žádný rollback build artefaktů není potřeba.

Runtime (`next start`) čte distDir z next.config bez env proměnné, takže servíruje standardní `.next` — env proměnnou nastavujte jen pro build.

Jak to poznat příště

• Chyby “Cannot find module …/.next/…” v logu s timestampy odpovídajícími deployům
• Stížnosti uživatelů “chvíli to nejelo a pak zas jo” po nasazení