Statikus Webalkalmazás Hosztolása Cloudflare Pages-En

A Cloudflare Pages hosztolás lehetővé teszi a frontend csapatok számára, hogy gyors, biztonságos kódot szállítsanak szerveradminisztráció nélkül. A Cloudflare Pages használatával a fejlesztők egy nagy teljesítményű, edge-natív platformot kapnak statikus webalkalmazások, egyoldalas alkalmazások (SPA) és szerveroldali renderelésű (SSR) keretrendszerek telepítéséhez. A Git-tárolóhoz való közvetlen csatlakozással a Cloudflare automatizálja a build folyamatokat, előnézeti verziókat (preview deployments) generál, és globálisan kiszolgálja az erőforrásokat. Ez az útmutató bemutatja, hogyan csatlakoztathatja a Git-et, hogyan konfigurálhatja a build beállításokat, hogyan állíthat be egyedi domaineket és hogyan kezelheti az átirányításokat.

Legfontosabb tudnivalók:

• Edge-natív frontend alkalmazások telepítése; a Cloudflare Pages globálisan, a Cloudflare hálózatának széléről (edge) szolgálja ki a fájlokat, garantálva a szubszekundumos betöltési időt.
• Automatizált Git integráció; csatlakoztassa a tárolóját a build folyamatok automatikus indításához és előnézeti URL-ek generálásához minden commit után.
• Keretrendszer-specifikus build beállítások; konfigurálja a kimeneti mappákat és parancsokat React, Vue, Next.js, Hugo vagy Astro projektekhez.
• Átirányítási és fejléc-szabályok megadása egyszerű szöveges _redirects és _headers fájlokkal a nyilvános (public) mappában.
• Egyedi domainek hozzárendelése ingyenes, automatikusan megújuló SSL tanúsítványokkal, amelyeket közvetlenül a Cloudflare kezel.

Mi az a Cloudflare Pages?

A Cloudflare Pages egy szerver nélküli (serverless) hosztolási platform frontend fejlesztők számára (hasonlóan a Netlify-hoz vagy a Vercel-hez), amely közvetlenül a Cloudflare globális infrastruktúrájára épül.

Ahelyett, hogy a fájlokat egyetlen felhőszerveren tárolná, a Cloudflare Pages elosztja a HTML, CSS, JavaScript fájlokat és képeket a világ különböző pontjain található edge szervereken. Amikor egy felhasználó lekéri az oldalt, az erőforrások a legközelebbi helyszínről töltődnek be, minimalizálva a hálózati késleltetést. A szerveroldali logikát igénylő projekteknél a Pages integrálható a Cloudflare Workers szolgáltatással háttérfunkciók futtatásához. A Pages és más edge számítási szolgáltatások összehasonlításához olvassa el a Cloudflare Pages vs. Workers útmutatónkat.

Előfeltételek

Mielőtt elkezdené, győződjön meg arról, hogy rendelkezik az alábbiakkal:

• Egy Git-tároló GitHub-on vagy GitLab-on, amely tartalmazza a projektjét (vagy a lefordított fájlokat közvetlen feltöltéshez).
• Egy statikus fájlokat generáló keretrendszer – React (Vite), Vue, Astro, SvelteKit, Hugo vagy egyszerű HTML. A szerveroldali renderelésű keretrendszerek is működnek a Pages Functions segítségével.
• Egy működő helyi build. Futtassa le helyben a build parancsot (például npm run build), és ellenőrizze, hogy a kimeneti mappa hibák nélkül generálódik-e, mielőtt bármit csatlakoztatna.
• Egy ingyenes Cloudflare fiók. Az ingyenes szinthez nincs szükség bankkártyára.
• Helyileg telepített Node.js (ajánlott), hogy reprodukálni tudja a buildeket, és használhassa a Wrangler parancssori eszközt.

Egy gyors helyi ellenőrzés órákig tartó hibakeresést spórolhat meg: ha az oldal helyben nem épül fel hibamentesen, a Cloudflare szerverein sem fog sikerülni. Először a helyi hibákat javítsa ki.

1. lépés: A Git-tároló csatlakoztatása

A kezdéshez jelentkezzen be a Cloudflare Dashboardra, navigáljon a Compute > Pages menüponthoz, majd kattintson a Create a project gombra.

Válassza a Connect to Git opciót GitHub vagy GitLab fiókja összekapcsolásához. Válassza ki a statikus webalkalmazást tartalmazó tárolót. Ez az integráció rendkívül hasznos, mivel létrehoz egy folyamatos integrációs (CI) csővezetéket: minden alkalommal, amikor kódot küld a produkciós branch-be, a Cloudflare automatikusan lefordítja és közzéteszi a frissítéseket. Más ágak (branches) esetén a Cloudflare egyedi előnézeti URL-eket (preview URLs) generál, így tesztelheti a változtatásokat a véglegesítés előtt.

2. lépés: A build beállítások konfigurálása

A Cloudflare Pages támogatja a népszerű statikus oldalgenerátorokat és frontend keretrendszereket. A beállítási varázsló során konfigurálja az alábbi paramétereket a projekt igényei szerint:

• Build command: A package.json fájlban meghatározott build parancs (például npm run build vagy hugo --minify).
• Build output directory: A lefordított statikus fájlokat tartalmazó mappa (például dist, build vagy public).
• Environment variables: Ha a build folyamat API-kulcsokat vagy konfigurációs változókat igényel, itt adhatja meg őket.

A Cloudflare automatikusan felismeri a legtöbb keretrendszert, de a beállítások ellenőrzésével elkerülhető az első sikertelen futás. A leggyakoribb kombinációk:

Rögzítse a Node verziót. A „helyben működik, de a Cloudflare-en nem” típusú hibák leggyakoribb oka a build környezet és a projekt által elvárt Node verziók eltérése. Adja meg ezt kifejezetten a környezeti változók között:

1NODE_VERSION = 20

Vagy hozzon létre egy .node-version fájlt a tároló gyökerében:

120

3. lépés: Átirányítások és fejlécek beállítása

Az egyoldalas alkalmazások (mint a React Router) vagy a korábbi URL-ek migrációja esetén konfigurálnia kell az útvonalirányítási és átirányítási szabályokat. A Pages ezt a kimeneti mappában elhelyezett egyszerű szöveges fájlok segítségével kezeli.

Átirányítások (_redirects)

Hozzon létre egy _redirects nevű fájlt a nyilvános (public) mappában. Ahhoz, hogy egy React SPA tisztán kezelje a kliensoldali útvonalakat, adja hozzá az alábbi fallback szabályt:

1/*  /index.html  200

Ez minden kérést az index.html fájlra irányít, lehetővé téve, hogy a JavaScript router kezelje az útvonalat.

A sorrend számít. A Cloudflare fentről lefelé értékeli a szabályokat, és megáll az első találatnál, ezért a specifikus átirányításoknak a catch-all szabály felett kell elhelyezkedniük:

1# Permanent redirect for a moved page
2/old-pricing   /pricing            301
3
4# Redirect an entire section, preserving the sub-path
5/blog/*        /articles/:splat    301
6
7# SPA fallback (must come last)
8/*             /index.html         200

A :splat helyőrző továbbítja az útvonal egyező részét a célállomásra. Az ingyenes csomag projektenként legfeljebb 2000 statikus átirányítási szabályt engedélyez. Ha ennél többre van szüksége, helyezze a logikát egy Pages Function-be vagy használja a Bulk Redirects eszközt.

Egyedi fejlécek (_headers)

Hozzon létre egy _headers nevű fájlt a biztonsági szabályok, Referrer-politikák vagy egyedi cache-szabályok megadásához:

1/*
2  X-Frame-Options: DENY
3  X-Content-Type-Options: nosniff
4  Referrer-Policy: strict-origin-when-cross-origin

Ugyanitt optimalizálhatja a gyorsítótárazást (caching) is. A verziózott, megváltoztathatatlan (immutable) fájlokat akár egy évre is cache-elheti, míg a HTML fájlokat frissen kell tartani, hogy a felhasználók mindig a legfrissebb verziót kapják:

1/assets/*
2  Cache-Control: public, max-age=31536000, immutable

Ha szeretné látni, hogyan viszonyulnak ezek a szabályok a hagyományos backend útvonalirányításhoz, olvassa el a szerver nélküli API építése Cloudflare Workers segítségével cikkünket.

4. lépés: Egyedi domainek hozzárendelése

A telepítés után a Cloudflare biztosít egy alapértelmezett aldomaint (például sajat-projekt.pages.dev).

Egyedi domain hozzárendeléséhez navigáljon a Pages projekt Custom Domains fülére, és adja meg a domain nevét (például sajatcég.hu). Ha a DNS-ét a Cloudflare kezeli, a platform automatikusan beállítja a CNAME rekordokat, és azonnal kiállít egy ingyenes, automatikusan megújuló SSL tanúsítványt. Ha segítségre van szüksége a domain hozzárendelésben, a DNS-kezelésben vagy a szerver biztonságában, tekintse meg a weboldal biztonsági audit oldalunkat.

5. lépés: Telepítés a Wrangler CLI használatával (Közvetlen feltöltés)

A Git integráció a legtöbb csapatnak ideális, de a Wrangler parancssori eszközzel közvetlenül a saját gépéről vagy egy meglévő CI/CD csővezetékből is telepíthet. Ez akkor hasznos, ha a build folyamat már fut például GitHub Actions-ben vagy GitLab CI-ben, és Ön csak a kész kimenetet szeretné feltölteni.

Telepítse a Wranglert és jelentkezzen be:

1npm install -g wrangler
2wrangler login

Futtassa le a buildet helyben, majd töltse fel a kimeneti mappát a megadott projektbe:

1npm run build
2wrangler pages deploy ./dist --project-name=my-web-app

Az első futtatás létrehozza a projektet, ha az még nem létezik. CI/CD környezetben az interaktív wrangler login helyett használjon egy API tokent környezeti változóként megadva:

1# .github/workflows/deploy.yml (excerpt)
2- name: Deploy to Cloudflare Pages
3  run: npx wrangler pages deploy ./dist --project-name=my-web-app
4  env:
5    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
6    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

A közvetlen feltöltés kikerüli a Cloudflare saját build lépését, így teljes kontrollt biztosít a fejlesztői eszköztár felett.

Gyakori hibák és elhárításuk

Néhány tipikus hiba felelős a sikertelen első telepítések többségéért:

• 404-es hiba egy SPA útvonal frissítésekor. Egy kliensoldali útvonal (pl. /dashboard) frissítésekor az oldal hibát jelez, mert nincs ilyen fizikai fájl a szerveren. A megoldás a /* /index.html 200 szabály a _redirects fájlban. Ellenőrizze, hogy ez a fájl valóban a build kimeneti mappájába kerül-e.
• A Cloudflare figyelmen kívül hagyja a _redirects vagy _headers fájlokat. Ezeknek a fájloknak a publikált kimeneti mappában kell lenniük. Vite, Astro vagy SvelteKit használata esetén helyezze őket a public/ (vagy static/) mappába, hogy a build folyamat érintetlenül másolja át őket.
• A build helyben lefut, de a Cloudflare-en elbukik. Ez szinte mindig Node verzióbeli eltérés vagy hiányzó környezeti változó miatt van. Rögzítse a Node verziót, és adja meg a build által igényelt változókat.
• Túl sok fájl vagy túl nagy telepítés. Egyetlen feltöltés legfeljebb 20 000 fájlt tartalmazhat, a fájlméret-limit pedig 25 MiB. A nagy médiafájlokat R2-ben vagy külső képszolgáltatóban tárolja, ne a statikus csomagban.
• Elavult elemek a frissítés után. A verziózott fájlok (pl. app.4f2c.js) agresszíven gyorsítótárazhatók, az index.html azonban nem. Tartsa az HTML fájlokat rövid cache-en.

Tesztelési és éles üzemi szempontok

A Cloudflare minden nem produkciós branchhez és pull requesthez létrehoz egy előnézeti telepítést (preview deployment), mindegyiket saját URL-en (például abc123.my-web-app.pages.dev). Mivel az előnézetek ugyanazon az edge hálózaton futnak, mint az éles oldal, megbízható helyet biztosítanak a változtatások áttekintésére a véglegesítés előtt.

Az éles kiadásoknál néhány vezérlőelem dönti el, hogy pusztán egy tárhelyről vagy egy megbízható munkafolyamatról van-e szó:

• Visszaállítások (rollbackek). Minden telepítés megőrződik, így egy hibás kiadás visszavonható, ha az irányítópulton másodpercek alatt visszaléptet egy korábbi buildet az éles környezetbe – újraépítés nélkül.
• Környezetek szétválasztása. Állítson be eltérő változókat a produkciós és az előnézeti környezethez, hogy az előnézeti buildek a staging API-kra mutassanak, ne az éles adatokra.
• Analitika és Core Web Vitals. Engedélyezze a Cloudflare Web Analytics szolgáltatást – adatvédelmi szempontból elsődleges és cookie-mentes –, hogy harmadik féltől származó szkript betöltése nélkül kövesse a valós felhasználói LCP-, CLS-értékeket és a forgalmat.
• Hozzáférés-vezérlés az előnézetekhez. Az előnézeti URL-ek alapértelmezetten nyilvánosak. Ha egy branch kiadatlan munkát tesz elérhetővé, helyezze a Cloudflare Access mögé, hogy csak a csapata nyithassa meg.

Ha ezeket korán bevezeti, a telepítései kiszámíthatók maradnak, ahogy a projekt növekszik, és egyre többen dolgoznak rajta.

Legfontosabb tudnivalók

• A Cloudflare Pages a globális edge hálózaton hosztolja a statikus alkalmazásokat, maximalizálva a betöltési sebességet.
• Automatisálja a telepítést a GitHub vagy GitLab összekapcsolásával, így minden commit automatikusan elindítja a buildet.
• Konfigurálja a build parancsokat és kimeneti könyvtárakat a használt keretrendszernek (React, Astro, Next.js, Hugo) megfelelően.
• Adja meg az átirányítási és biztonsági szabályokat az output mappába helyezett egyszerű _redirects és _headers fájlokkal.
• Rendeljen egyedi domaineket ingyenes, automatikusan megújuló SSL tanúsítványokkal közvetlenül a Cloudflare kezelésében.

Optimalizálja webes infrastruktúráját

A gyors és biztonságos frontendek biztosításához a megfelelő tárhely-architektúra és caching-szabályok kiválasztása szükséges. A Mecanik a weboldal fejlesztési szolgáltatásokra és a professzionális technikai SEO audit szolgáltatásokra szakosodott. Egyedi, Core Web Vitals-ra optimalizált React, Next.js és Astro platformokat építünk, amelyeket a Cloudflare-re telepítünk. Lépjen kapcsolatba velünk még ma, és beszéljük meg a következő projektjét.

Gyakran ismételt kérdések (GYIK)

Mi az a Cloudflare Pages hosztolás? Ez egy szerver nélküli frontend hosztolási platform, amely statikus webalkalmazásokat, React SPA-kat és statikus oldalgenerátor kimeneteket (például Astro vagy Hugo) épít fel és szolgál ki globálisan a Cloudflare CDN hálózatán.

Támogatja a Cloudflare Pages a szerveroldali renderelést (SSR)? Igen. A Pages támogatja az SSR keretrendszereket (mint a Next.js, Astro, SvelteKit) azáltal, hogy a szerveroldali logikát a build folyamat során automatikusan szerver nélküli Cloudflare Workers funkciókká alakítja.

Hogyan állíthatok be átirányításokat Cloudflare Pages-en? Hozzon létre egy egyszerű szöveges fájlt _redirects néven a build kimeneti könyvtárában, és adja meg az átirányítási szabályokat a forrás útvonal, a cél útvonal és a HTTP státuszkód megadásával.

Ingyenes a Cloudflare Pages? Igen. A Cloudflare Pages rendkívül nagylelkű ingyenes szintet kínál, amely korlátlan telepítést, korlátlan sávszélességet és egyedi domainek használatát biztosítja, így kiemelkedően költséghatékony választás.

Hogyan állíthatok be egyedi domaint a Pages-en? Navigáljon a Custom Domains fülre a Pages projekt irányítópultján, adja meg a domain nevét, és a Cloudflare automatikusan beállítja a szükséges DNS rekordokat és kiállítja a tanúsítványt.