Proč nám Cloudflare Pages tiše neprošel build

Nasazení tohoto webu selhávalo třikrát za sebou a pokaždé z jiného důvodu. Všechny tři vypadaly zvenčí stejně: v dashboardu červený build, na doméně pořád stará verze. Píšu to sem, protože ani jedna z těch chyb nebyla v kódu.

1. Binární lockfile, který build image neumí přečíst

Cloudflare pouští bun install --frozen-lockfile. Jeho bun 1.2.15 narazil na starší binární formát:

Outdated lockfile version: failed to parse lockfile: 'bun.lockb'
warn: Ignoring lockfile
error: lockfile had changes, but lockfile is frozen

Bun od verze 1.2 používá textový bun.lock. Lokální bun si binární soubor pořád aktualizoval, takže lokálně nic nenapovědělo, že je něco špatně. Řešení je jednoduché:

rm bun.lockb
bun install --save-text-lockfile

Textový lockfile má navíc tu výhodu, že se dá číst v code review.

2. Node starší, než Astro vyžaduje

Po opravě lockfilu se build dostal dál a spadl jinde. Build image nabízel Node 18.17.1, Astro 5 vyžaduje ^18.20.8 || ^20.3.0 || >=22. Rozdíl tří patch verzí.

Cloudflare čte .node-version, takže stačí jeden řádek v repozitáři:

22

Verzovaný soubor je lepší než proměnná v dashboardu. Příští člověk uvidí, proč tam je.

3. packageManager v package.json

Tuhle jsem způsobil sám při opravě předchozí. Přidal jsem:

"packageManager": "[email protected]"

Cloudflare podle toho nainstaloval správnou verzi bunu, ale přeskočil instalaci závislostí. V logu prostě zmizel řádek Installing project dependencies a build rovnou spustil příkaz:

Executing user command: bun run build
$ astro build
/usr/bin/bash: line 1: astro: command not found

Astro nebylo nainstalované, protože bun install nikdy neproběhl.

Pole jsem odstranil a build command nastavil tak, aby na detekci vůbec nezávisel:

bun install --frozen-lockfile && bun run build

Co si z toho odnést

Všechny tři chyby byly v prostředí, ne v aplikaci. Lokální build procházel po celou dobu, což je přesně ten případ, kdy člověk hledá na špatném místě.

Jediné, co doopravdy pomohlo, bylo přečíst si build log celý, řádek po řádku. Chybová hláška na konci (command not found) ukazovala na následek. Příčina byla o patnáct řádků výš, v tom, co v logu chybělo.