Jak wdrozyc statyczna strone na Cloudflare Workers w 2025

Ostatnio testowany: Pazdziernik 2025 | Wrangler: 3.x | Node.js: 20+ | Platforma: macOS/Linux/Windows

Jesli wdrazales na Cloudflare Pages przez ich integracje Git, mogles zauwazyc nowa wiadomosc o deprecjacji: Cloudflare zdeprecjonowal Pages w kwietniu 2025. Przesuwaja wszystkich na Cloudflare Workers.

Na poczatku brzmi to irytujaco. Pages byl bardzo prosty - podlacz repo, ustaw polecenie build, gotowe. Workers? To brzmi jakbys musial pisac funkcje serverless i rozumiec edge computing i... tak, moze to byc przytlaczajace jesli nie wiesz od czego zaczac.

Oto dobra wiadomosc: wdrazanie statycznej strony na Workers jest proste gdy zrozumiesz workflow. I dostajesz wieksza kontrole nad wdrozeniami w tym procesie.

Czego potrzebujesz

Zanim zaczniemy, upewnij sie ze masz:

1. Statyczna strone (Gatsby, Next.js static export, React build, Hugo, Astro)
2. Node.js 20+ zainstalowany
3. Konto Cloudflare (darmowy tier wystarczy)
4. Wrangler CLI (zainstalujemy to)

Krok 1: Zainstaluj Wrangler

Wrangler to narzedzie linii polecen Cloudflare do wdrazania na Workers. Dodaj do projektu:

npm install -D wrangler

Krok 2: Uwierzytelnij Wrangler

Zanim bedziesz mogl wdrazac, musisz polaczyc Wrangler z kontem Cloudflare:

npx wrangler login

To otwiera przegladarke i prosi o autoryzacje Wrangler. Kliknij "Allow" i gotowe.

Krok 3: Utworz wrangler.toml

Wrangler potrzebuje pliku konfiguracyjnego w glownym katalogu projektu. Utworz wrangler.toml:

name = "your-project-name"
compatibility_date = "2025-10-19"

# Wskazuje Wranglerowi gdzie sa twoje pliki statyczne
pages_build_output_dir = "public"

[site]
bucket = "./public"

Dla strony Gatsby katalog wyjsciowy to public. Dla Next.js to out. Dla Create React App to build.

Krok 4: Zbuduj strone

Nic sie tu nie zmienia. Uruchom normalne polecenie build:

# Gatsby
npm run build

# Next.js (static export)
npm run build && npm run export

# Create React App
npm run build

Krok 5: Wdroz na Workers

Oto magiczne polecenie:

npx wrangler pages deploy public

Zamien public na swoj katalog wyjsciowy.

Pierwsze wdrozenie? Wrangler zapyta:

✔ Enter the name of your new project: … your-site-name
✔ Enter the production branch name: … main

Po tym Wrangler buduje i wdraza twoja strone. Dostaniesz URL typu:

https://your-site-name.pages.dev

Krok 6: Dodaj skrypty deploy do package.json

Wpisywanie npx wrangler pages deploy public za kazdym razem jest nuzace. Dodaj skrypty do package.json:

{
  "scripts": {
    "build": "gatsby build",
    "deploy": "npm run build && wrangler pages deploy public",
    "deploy:prod": "npm run build && wrangler pages deploy public --branch=main"
  }
}

Teraz wdrazanie to:

npm run deploy

Krok 7: Konfiguracja wlasnej domeny

Twoj URL .pages.dev dziala, ale pewnie chcesz wlasna domene.

Przez Dashboard Cloudflare (Najlatwiej)

1. Zaloguj sie do Cloudflare Dashboard na https://dash.cloudflare.com
2. W lewym pasku kliknij Workers & Pages
3. Znajdz projekt i kliknij na niego
4. Kliknij zakladke Custom domains na gorze
5. Kliknij Set up a custom domain
6. Wpisz domene (np. example.com)
7. Kliknij Continue
8. Kliknij Activate domain

Wazne:

• Twoja domena musi juz byc na Cloudflare DNS
• Certyfikaty SSL sa automatycznie generowane
• Rekordy DNS sa automatycznie tworzone

Krok 8: Automatyczne wdrozenia z GitHub Actions

Stary flow Pages auto-wdrazal gdy pushowales na main. Mozemy to odtworzyc z GitHub Actions.

Utworz .github/workflows/deploy.yml:

name: Deploy to Cloudflare Workers

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build site
        run: npm run build

      - name: Deploy to Cloudflare Workers
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy public --project-name=your-project-name

Pobierz dane uwierzytelniajace Cloudflare

Potrzebujesz dwoch rzeczy:

1. Account ID:

• Wejdz do Cloudflare Dashboard
• Kliknij Workers & Pages
• Twoje Account ID jest w prawym pasku bocznym

2. API Token:

• Wejdz do My Profile -> API Tokens
• Kliknij Create Token
• Uzyj szablonu "Edit Cloudflare Workers"
• Skopiuj token (widzisz go tylko raz!)

Dodaj Secrets do GitHub

Wejdz do repo -> Settings -> Secrets and variables -> Actions -> New repository secret

Dodaj:

• CLOUDFLARE_API_TOKEN: Twoj token API
• CLOUDFLARE_ACCOUNT_ID: Twoje ID konta

Teraz kazdy push na main uruchamia wdrozenie automatycznie.

Typowe problemy i rozwiazania

Problem 1: Konflikty zaleznosci

Jesli migrujesz z Pages i napotykasz bledy npm:

Utworz .npmrc w glownym katalogu projektu:

legacy-peer-deps=true

Problem 2: Zla wersja Node

Workers domyslnie uzywa Node 20+. Jesli projekt wymaga konkretnej wersji, zablokuj ja:

Utworz .nvmrc:

20

Podsumowanie

Cloudflare zabijajacy Pages i zmuszajacy wszystkich do Workers na poczatku wydaje sie krokiem w tyl. Auto-deploy oparty na Git byl naprawde wygodny.

Ale gdy skonfigurujesz Wrangler i CI/CD, dostajesz:

• Pelna kontrole nad tym kiedy i jak wdrazasz
• Szybsze wdrozenia (bez czekania w kolejce build Cloudflare)
• Lepsze debugowanie (mozesz testowac buildy lokalnie przed wdrozeniem)
• Dostep do funkcji Workers (functions, KV storage, edge logic)

Poczatkowa konfiguracja zajmuje 20 minut. Po tym to git push i GitHub Actions zajmuje sie reszta - to samo doswiadczenie co Pages, ale z wieksza moca pod maska.