Deploy Cloudflare Workers-re

17.1Mit deployolsz valójában?

A 2. modulból tudod, hogy a build végén egy .output/ könyvtár keletkezik. Deploy szempontjából ez két, gyökeresen eltérő természetű dolog egy mappában:

17.2A kérés útja: előbb asset, aztán Worker

A Cloudflare alapértelmezett sorrendje egyszerű: ha a kért URL egyezik egy fájllal az asset-könyvtárban, azt szolgálja ki — anélkül, hogy a Worker-kód lefutna. Csak ha nincs találat, kerül a kérés a Workerhez.

GET /_nuxt/entry.a1b2c3.js   →  asset találat  →  kiszolgálva, a Worker nem fut
GET /termek/bogre            →  nincs asset    →  Worker: SSR
GET /api/orders              →  nincs asset    →  Worker: server route

Az előrenderelt oldal csapdája

Itt kapcsolódik össze a 7. modul a mostanival, és ez a kapcsolat okoz éles hibákat. Ha egy útvonalra prerender: true route rule-t tettél, abból fájl lesz a .output/public/-ban. Fájl → asset → a Worker nem fut le rá.

Ami azt jelenti, hogy azon az útvonalon:

• nem fut le a server middleware — nincs tenant-feloldás, nincs auth-ellenőrzés, nincs fejléc-injektálás;
• nincs dinamikus tartalom — amit a build idején tudtál, azt kapja a felhasználó;
• viszont ingyen van, és nulla késleltetéssel, a felhasználóhoz legközelebbi ponton.

Ez nem hiba, hanem a prerendering lényege — de meg kell lepődni tudni rajta. A klasszikus baleset: kiteszel egy prerender: true-t a marketing-főoldalra, majd három hónappal később valaki felvesz egy server middleware-t, ami minden kérésnél naplózza a látogatót — és nem érti, miért hiányzik a főoldal a statisztikából.

17.3A wrangler.jsonc anatómiája — soronként

Íme egy éles Nuxt-app teljes konfigurációja, kommentekkel. A $schema-sor nem kötelező, de a szerkesztőd ettől fogja tudni, mit ajánljon fel.

{
  "$schema": "node_modules/wrangler/config-schema.json",

  // ——— identitás ———
  "name": "bolt",
  "main": ".output/server/index.mjs",       // a Nitro kimenete — build UTÁN létezik
  "compatibility_date": "2026-08-01",
  "compatibility_flags": ["nodejs_compat"], // Nuxt-nál gyakorlatilag kötelező

  // ——— a statikus fele ———
  "assets": {
    "directory": ".output/public",
    "binding": "ASSETS"                    // csak ha kódból is olvasnál assetet
  },

  // ——— megfigyelhetőség (16. modul) ———
  "observability": { "enabled": true, "head_sampling_rate": 1 },
  "upload_source_maps": true,

  // ——— futásidő ———
  "placement": { "mode": "smart" },        // megfontolandó — lásd 17.9
  "limits": { "cpu_ms": 50 },              // önvédelem a végtelen ciklus ellen

  // ——— konfiguráció (12. modul) ———
  "vars": {
    "NUXT_PUBLIC_SITE_URL": "https://bolt.hu"
  },

  // ——— bindingok (11. modul) ———
  "hyperdrive": [{ "binding": "DB", "id": "…" }],
  "kv_namespaces": [{ "binding": "CACHE", "id": "…" }],
  "r2_buckets": [{ "binding": "MEDIA", "bucket_name": "bolt-media" }],

  // ——— hova válaszoljon ———
  "routes": [{ "pattern": "bolt.hu", "custom_domain": true }],
  "workers_dev": false,                    // éles appnál kapcsold ki
  "preview_urls": true,                    // de a preview URL-eket hagyd meg!

  // ——— környezetek ———
  "env": {
    "staging": {
      "name": "bolt-staging",
      "routes": [{ "pattern": "staging.bolt.hu", "custom_domain": true }],
      "vars": { "NUXT_PUBLIC_SITE_URL": "https://staging.bolt.hu" },
      "hyperdrive": [{ "binding": "DB", "id": "…másik…" }],
      "kv_namespaces": [{ "binding": "CACHE", "id": "…másik…" }],
      "r2_buckets": [{ "binding": "MEDIA", "bucket_name": "bolt-media-staging" }]
    }
  }
}

Két apró, de fontos kapcsoló

A workers_dev: false és a preview_urls: true párost érdemes tudatosan beállítani. Az első kikapcsolja az appnév.subdomain.workers.dev címet — éles alkalmazásnál ez kívánatos, mert különben az appod két különböző URL-en érhető el (SEO-duplikáció, és egy nyitva felejtett hátsó ajtó). A második viszont maradjon bekapcsolva, mert a 17.6-os workflow épp erre épül. A preview_urls alapértéke a workers_dev értéke, tehát ha az elsőt kikapcsolod, a másodikat explicit vissza kell kapcsolnod.

17.4Négy deploy-modell

Ugyanaz a wrangler.jsonc négyféle úton juthat el a Cloudflare-hez. Nem ízlés kérdése, melyiket választod — a csapat mérete és a megfelelőségi igény dönti el.

# a minimum, ami mindegyik modellben ugyanaz
npx nuxt build          # előállítja a .output/-ot
npx wrangler deploy     # feltölti a Workert + az asseteket

17.5Verziók: a globálisan azonnali deploy megszelídítése

A Workers-deploy globális és azonnali — nincs „egy régióban élesítjük, aztán figyeljük”. Ez remek, amíg jó a kód, és katasztrófa, amikor nem. A Cloudflare erre a verzió fogalmát adja: a feltöltést és a forgalomra állítást szétválasztja.

# ① feltöltés — verzió jön létre, de NEM kap forgalmat
npx wrangler versions upload

# ② forgalomra állítás, akár fokozatosan
npx wrangler versions deploy                       # interaktív: százalékok bekérése
npx wrangler versions deploy <uj-id>@10 <regi-id>@90

# ③ állapot és visszalépés
npx wrangler versions list
npx wrangler deployments status
npx wrangler rollback <verzio-id> --message "500-asok a checkoutban"

Két dokumentált korlátot érdemes fejben tartani: fokozatos kigördítésben csak az utolsó 100 feltöltött verzió vehet részt, és egy Durable Objectből egyszerre csak egy verzió futhat — vagyis ha van DO-d, a kigördítés nem tudja két verzióra osztani.

A Nuxt-specifikus veszély a fokozatos kigördítésben

A dokumentáció világosan fogalmaz: minden kérés függetlenül van irányítva a beállított százalékok szerint. Egymás utáni kérések tehát különböző verziókhoz kerülhetnek. Egy Nuxt-appnál ennek konkrét következménye van.

A felhasználó megkapja a B verzió által renderelt HTML-t, benne a B verzió chunk-hivatkozásaival (/_nuxt/entry.uj-hash.js). A böngésző azonnal kéri a chunkot — és ez a kérés a százalékos szórás miatt az A verzióhoz kerülhet, ahol az a fájl nem létezik. Eredmény: 404 a chunkra, vagyis pontosan az a chunk-hiba, amit a 16.9-ben tárgyaltunk — csak most nem deploy után, hanem deploy közben, tartósan.

17.6Preview URL-ek — a 16. modul füsttesztjének a lába

Minden feltöltött verzió kap egy saját, azonnal elérhető URL-t, forgalom nélkül. Ez az a pont, ahol a 16.6-ban felépített füstteszt bekapcsolódik.

# verziós preview URL — automatikus, hash-elt előtaggal
npx wrangler versions upload
# → https://a1b2c3d4-bolt.<subdomain>.workers.dev

# aliasolt preview URL — beszédes és állandó
npx wrangler versions upload --preview-alias pr-142
# → https://pr-142-bolt.<subdomain>.workers.dev

Az alias formátuma <alias>-<worker-név>.<subdomain>.workers.dev; kisbetű, szám és kötőjel megengedett, a worker névvel együtt legfeljebb 63 karakter. Ezzel a PR-számból generált alias tökéletes: minden pull requestnek stabil, megosztható URL-je lesz, amit a review-ban a terméktulajdonos is meg tud nyitni.

17.7Két környezet-rendszer, amit össze kell fésülni

Itt egy olyan zavar keletkezik, ami sok időt tud elvinni: a Nuxt-nak és a wranglernek is van „környezet” fogalma, és nem ugyanaz a kettő.

# a helyes párosítás: MINDKETTŐT meg kell adni
npx nuxt build --envName staging          # Nuxt-oldali build-konfig
npx wrangler deploy --env staging         # melyik Worker + melyik bindingok

17.8Secretek a deploy körül

# interaktívan bekérve
npx wrangler secret put NUXT_SESSION_PASSWORD
npx wrangler secret put NUXT_SESSION_PASSWORD --env staging

# CI-ből, csővezetéken
echo "$SESSION_PASSWORD" | npx wrangler secret put NUXT_SESSION_PASSWORD

# egy KONKRÉT verzióhoz (a fokozatos kigördítés miatt fontos)
npx wrangler versions secret put STRIPE_KEY

17.9Smart Placement — kell egy Nuxt-appnak?

A Smart Placement azt csinálja, hogy a Workeredet nem a felhasználóhoz, hanem a backendedhez közel futtatja. Kapcsoló egy sor:

"placement": { "mode": "smart" }

Elsőre ez visszafelé hangzik — nem az volt az edge lényege, hogy közel legyünk a felhasználóhoz? De gondold végig egy SSR-oldal aritmetikáját. Tegyük fel, hogy a renderelés három egymás utáni lekérdezést igényel egy frankfurti Postgresből, és a felhasználó Budapesten van:

A logika: egy lassú körutat cserélsz N lassú körútra. Minél többször fordul a kódod az adatbázishoz egyetlen kérés alatt, annál nagyobb a nyereség.

És — ez a lényeges rész — a statikus asseteket ez nem érinti: azokat a Cloudflare mindig a kéréshez legközelebbi helyről szolgálja ki, függetlenül a Worker elhelyezésétől. Vagyis nem áldozod fel a képek és JS-fájlok sebességét.

17.10Migrációk és a deploy sorrendje

A 11. modul séma-migrációi és ez a modul itt találkoznak, és ez a találkozás okozza a legcsúnyább éles hibákat. A kérdés egyszerű: előbb a migráció vagy előbb a kód?

A válasz az, hogy egyik sorrend sem biztonságos önmagában, mert bármelyiket választod, lesz egy időablak, amikor a futó kód és a séma nem illik össze. Workers-en ez rosszabb, mint máshol: a deploy globálisan azonnali, fokozatos kigördítésnél pedig szándékosan két kódverzió fut egyszerre.

Az egyetlen működő minta a bővítés-szűkítés (expand–contract), három deployban:

17.11Amikor elhasal — hibakatalógus

17.12A deploy-checklist

Mielőtt egy Nuxt-app először élesbe megy Workers-en, ezeken menj végig. Mindegyik egy-egy korábbi modul zárókövét húzza be:

1. A build és a deploy egy scriptben van, hogy ne lehessen külön futtatni őket.
2. nodejs_compat bekapcsolva, compatibility_date friss és tudatosan választott.
3. Az assets.directory a .output/public, a not_found_handling az alapértelmezett none.
4. Minden binding minden környezetben szerepel — külön átnézve, nem feltételezve.
5. Secretek feltöltve minden környezetbe, és a NUXT_SESSION_PASSWORD legalább 32 karakter (10. modul).
6. observability.enabled és upload_source_maps bekapcsolva — a hibakeresés előfeltételei (16. modul).
7. A bundle mérete és az indulási idő mérve, a limitek 80%-ánál CI-kapuval (15. modul).
8. Füstteszt fut egy preview URL ellen a forgalomra állítás előtt (16.6).
9. A migrációk bővítés-szűkítés mintát követnek, hogy a rollback tényleg működjön.
10. workers_dev: false, hogy az app ne legyen elérhető két URL-en.

17.13Ellenőrizd magad