Seitenfunktionen: wann anstelle von reinen Workern zu verwenden

Es gibt ein weit verbreitetes Missverständnis über Seitenfunktionen: dass es sich um eine vereinfachte oder eingeschränkte Version von Workers handelt, die für triviale Fälle geeignet und für ernsthafte Produktion unzureichend ist. Das stimmt nicht. Seitenfunktionen werden auf derselben V8-Laufzeitumgebung wie Worker ausgeführt, greifen auf dieselben Bindungen zu und respektieren dieselben Einschränkungen. Der Unterschied zwischen den beiden Einsatzformen liegt nicht in der Kapazität, sondern im betrieblichen Kontext.

Was Seitenfunktionen sind, technisch gesehen

Pages-Funktionen sind Worker, die über Dateisystemkonventionen innerhalb eines Pages-Projekts bereitgestellt werden. Sie erstellen ein Verzeichnis /functions im Stammverzeichnis des Repositorys und jede TypeScript- oder JavaScript-Datei dort wird zu einer Route. Datei /functions/api/users/[id].ts antwortet in /api/users/:id. Datei /functions/webhooks/stripe.ts antwortet in /webhooks/stripe.

Die Laufzeit, die diesen Code ausführt, ist identisch mit der eines eigenständigen Workers: V8 isoliert, Kaltstart unter 1 ms, 128 MB Speicher pro Aufruf (hartes Limit), 30 Sekunden CPU pro Anfrage im kostenpflichtigen Plan, 1.000 Unteranfragen pro Aufruf. Die verfügbaren Bindungen sind die gleichen: D1 für die SQLite-Datenbank am Edge, KV für die Schlüsselwertspeicherung, R2 für Objekte, dauerhafte Objekte für konsistenten Zustand, AI für Inferenz, Service-Bindungen für direkte Aufrufe an andere Worker.

Der Unterschied besteht bei der Bereitstellung: Eine Pages-Funktion wird als Teil eines Pages-Projekts erstellt, das auch über statische Assets verfügt. Es ist nicht möglich, eine Pages-Funktion ohne ein Pages-Projekt bereitzustellen. Hierbei handelt es sich nicht um eine technische Einschränkung, sondern um eine Produktauswahl, die definiert, wann die Verwendung des einen oder anderen sinnvoll ist.

Wenn Seitenfunktionen gewinnen

Das stärkste Argument für Pages Functions ist die gemeinsame Platzierung: Frontend und Backend im selben Repository, mit demselben Bereitstellungszyklus. Ein Next.js-, Astro- oder SvelteKit-Projekt mit API-Routen ist natürlich am selben Ort – Sie ändern eine Komponente und die API-Route, die sie im selben Commit, derselben Pull-Anfrage und derselben Vorschaubereitstellung verwendet.

Diese Vorschau pro Zweig ist das konkreteste betriebliche Unterscheidungsmerkmal. Bei jedem Push an einen Zweig wird eine Vorschau-URL im Format hash-nome-da-branch.seuproject.pages.dev generiert, in der sowohl statische Assets als auch Funktionen ausgeführt werden. Das bedeutet, dass der PR-Prüfer die gesamte Funktion – Schnittstelle und API – testen kann, ohne sie in einer separaten Umgebung bereitzustellen. Pure Worker haben diesen Ablauf nicht von Haus aus.

Wenn Ihr API-Routing natürlich auf URL-Pfade abgebildet wird und Sie keine komplexe Routing-Logik außerhalb der Verzeichnisstruktur benötigen, machen Pages Functions die Notwendigkeit eines separaten Workers mit eigenen, in wrangler.toml konfigurierten Routen überflüssig.

Die Verzeichnisstruktur und das Middleware-Muster

Eine realistische Pages with Functions-Projektstruktur:

/functions
  _middleware.ts          ← executa antes de toda Function no diretório
  /api
    _middleware.ts        ← executa antes de toda Function em /api
    users/
      [id].ts             ← GET /api/users/:id, PUT /api/users/:id
      index.ts            ← GET /api/users, POST /api/users
    webhooks/
      stripe.ts           ← POST /api/webhooks/stripe

Die _middleware.ts-Datei ist ein Kompositionsmechanismus, den viele Leute ignorieren. Er empfängt die Anfrage vor der Ausführung der pfadspezifischen Funktion und kann diese mit seiner eigenen Antwort kurzschließen oder über ctx.next() an den nächsten Handler weitergeben. Dies gilt für Authentifizierung, zentralisierte Protokollierung und CORS ohne Wiederholung der Logik in jeder Funktion:

// /functions/api/_middleware.ts
export async function onRequest(ctx: EventContext<Env, any, any>) {
  const token = ctx.request.headers.get("Authorization");
  if (!token || !isValidToken(token, ctx.env.JWT_SECRET)) {
    return new Response("Unauthorized", { status: 401 });
  }
  const response = await ctx.next();
  response.headers.set("X-Content-Type-Options", "nosniff");
  return response;
}

Die Middleware im Root /functions deckt alle Funktionen ab. Die Middleware in /functions/api deckt nur API-Routen ab. Sie können die beiden stapeln – derjenige im übergeordneten Verzeichnis wird zuerst ausgeführt.

Wenn reine Arbeiter die richtige Wahl sind

Seitenfunktionen unterstützen keine Cron-Trigger. Wenn Sie einen Job benötigen, der um 3 Uhr morgens ausgeführt wird, um die Abrechnung zu verarbeiten, einen externen Feed zu synchronisieren oder abgelaufene Sitzungen zu bereinigen, muss es sich um einen eigenständigen Worker mit [triggers] crons auf wrangler.toml handeln. Innerhalb des Pages-Modells gibt es keine Alternative.

Warteschlangenkonsumenten – Worker, die Cloudflare Queues-Nachrichten asynchron verarbeiten – gibt es in Pages ebenfalls nicht. Wenn Ihre Architektur Warteschlangen verwendet, um die schwere Verarbeitung vom kritischen Pfad der Anforderung zu entkoppeln, muss der Verbraucher ein separater Worker sein.

Workers for Platforms, der Versandmechanismus für vom Benutzer bereitgestellte Skripte (im Fall von SaaS mit mehreren Mandanten, bei dem jeder Kunde seinen eigenen Code hat), ist exklusiv für Workers. E-Mail-Mitarbeiter, die eingehende E-Mails empfangen und verarbeiten, ebenso.

Als Faustregel gilt: Wenn der Trigger kein HTTP-Request ist, handelt es sich um einen reinen Worker. Seitenfunktionen sind ausschließlich HTTP.

Gemeinsamer Code zwischen separaten Seitenfunktionen und Workern

Eine gemeinsame Architektur verwendet sowohl das Pages-Projekt für das Frontend als auch die Haupt-API in /functions sowie separate Worker für Hintergrundjobs. Das Problem besteht darin, dass der Geschäftscode möglicherweise gemeinsam genutzt werden muss – Datenvalidierung, D1-Datenbankzugriff, Autorisierungslogik.

Die Lösung sind interne npm-Pakete (unter Verwendung von npm/pnpm-Arbeitsbereichen) oder ein dedizierter Worker als „Service-Schicht“, auf den andere über Service-Bindung zugreifen. Mit der Servicebindung kann eine Pages-Funktion einen Worker direkt im selben internen Cloudflare-Netzwerk aufrufen, ohne Netzwerkkosten und ohne Umweg über das öffentliche Internet:

// /functions/api/orders/index.ts
export async function onRequestPost(ctx: EventContext<Env, any, any>) {
  // Chama o Worker de processamento via Service Binding
  const result = await ctx.env.ORDER_PROCESSOR.fetch(
    new Request("https://internal/process", {
      method: "POST",
      body: ctx.request.body,
    })
  );
  return result;
}

Der ORDER_PROCESSOR hier ist ein eigenständiger Worker, der Zugriff auf Warteschlangen, Crons und alle anderen Grundelemente hat, die von Pages Functions nicht unterstützt werden. Seitenfunktionen befinden sich auf der HTTP-Ebene. Autonome Arbeiter sitzen in asynchronen Triggern. Die beiden teilen sich D1- und KV-Bindungen, die auf dieselben Ressourcen verweisen.

Die Entscheidungskriterien

Wenn Sie ein Projekt mit einem Frontend erstellen – also allem, was beim Erstellen statische Assets generiert –, beginnen Sie mit Pages. Die Funktionen, die Sie in /functions hinzufügen, haben genau die gleiche Leistung wie ein eigenständiger Worker für HTTP-Fälle. Sie erhalten eine Branch-Vorschau und eine integrierte Build-Pipeline, ohne zusätzliche Betriebskosten zu zahlen.

Wenn Sie einen Dienst ohne Frontend, mit Nicht-HTTP-Triggern oder für den benannte Umgebungen mit unterschiedlichen Bindungen für Staging und Produktion erstellen, ist Workers der direkteste Weg. Die explizite Konfiguration in wrangler.toml ist überprüfbarer und das Bereitstellungsmodell ist flexibler für reine Backend-Dienste.

Die beiden schließen sich nicht gegenseitig aus. Bei den meisten ernsthaften Projekten gibt es beides: Seiten für HTTP, die zusammen mit dem Frontend platziert sind, und Worker für asynchrone oder geplante Seiten.