Next.js-Captcha lösen im Route Handler (Node.js SDK)

next.js captcha - Next.js CAPTCHA: Solve It in a Route Handler (Node.js SDK)

Um ein Next.js-Captcha aus Server-Code zu lösen, rufen Sie CapSkip in einem App Router Route Handler auf, der auf der Node.js-Runtime läuft, und geben dann den Token zurück oder verwenden ihn in derselben Anfrage. Dieser Leitfaden richtet sich an Entwickler, deren Next.js-Server ein Captcha auf einer fremden Seite bestehen muss, nicht an alle, die eines in die eigene Website einbauen wollen. Der Handler fordert beim Paket capskip 1.7.0 einen Cloudflare-Turnstile-Token an, hält seine Secrets auf dem Server und setzt einen Timeout, der zum Funktionslimit passt. Jeder Task geht an den CapSkip Turnstile Solver, der auf einem Windows-PC läuft, den Sie besitzen, und nichts pro Lösung berechnet.

Was Sie brauchen

  • Ein Windows-PC, auf dem CapSkip läuft. Der Local-Modus lauscht standardmäßig auf 127.0.0.1, Port 8080. Die Installationsschritte stehen in der Einrichtungsanleitung.
  • Node.js 20.9 oder neuer, die Untergrenze im Feld engines von Next.js 16.4.6. Das Paket capskip selbst deklariert Node.js 18. Ich habe 20.11.1 und 24.22.0 mit npm 11.19.1 verwendet.
  • Eine Seite mit einem Turnstile-Widget, die Sie automatisieren dürfen, ihre URL und den sitekey aus dem Attribut data-sitekey des Widgets.
  • Eine Adresse für CapSkip, die Ihr Next.js-Server erreichen kann: 127.0.0.1 auf Ihrem eigenen PC, auf einer Hosting-Plattform der Server-Modus.

Alles hier lief gegen zwei Mocks, die ich geschrieben habe: Der eine spielt die CapSkip-Endpunkte in.php und res.php, der andere eine Anmeldeseite, die einen Turnstile-Token prüft. Die echte CapSkip-App bekam keinen Task, daher ist keine der Lösungszeiten unten eine echte, und auf einer Hosting-Plattform wurde nichts deployt. Turnstile dient als Beispiel, weil sein Aufruf nur einen sitekey und eine Seiten-URL braucht; jeder andere Typ, den das Paket löst, passt in denselben Helper.

Schritt 1: Projekt anlegen und die Secrets auf dem Server halten

Führen Sie dies in einem leeren Ordner in Windows PowerShell aus. Die Zeile, die das Feld type löscht, ist nötig: npm 11.19.1 schreibt für type den Wert commonjs, und Next.js 16.4.6 weigerte sich dann zu bauen.

# Windows PowerShell, in an empty folder
npm init -y
npm pkg delete type
npm install next react react-dom capskip server-only
npm install -D typescript @types/node @types/react
mkdir lib, app\api\turnstile

Legen Sie in diesem Ordner eine Datei namens .env.local an. Next.js lädt sie für next dev und next start. Kein Name beginnt mit NEXT_PUBLIC_, und das ist wichtig: Next.js ersetzt einen Verweis auf eine solche Variable im Browser-Code beim Build durch ihren Wert. Ich habe mit einer gebaut, auf die eine Client Component verwies, und ihr Wert stand in einer Datei unter .next/static. Eine Variable mit Präfix, auf die nichts verwies, und eine ohne Präfix tauchten dort in keiner Datei auf.

# .env.local
CAPSKIP_HOST=127.0.0.1
CAPSKIP_PORT=8080
CAPSKIP_API_KEY=YOUR_API_KEY
SOLVE_SECRET=YOUR_LONG_RANDOM_STRING

Bei ausgeschalteter API Key Validation akzeptiert CapSkip jeden Schlüsselwert, die Key-Zeile spielt also erst eine Rolle, wenn Sie die Validierung einschalten. SOLVE_SECRET ist das Passwort für Ihre eigene Route (Schritt 3). Next.js braucht außerdem ein Root-Layout:

// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Schritt 2: Ein Helper, der mit CapSkip spricht

Halten Sie das SDK in einer einzigen Datei, die nur der Server importieren kann. Ihre erste Zeile, der Import von server-only, macht aus einem Fehler einen Build-Fehler. Als eine Client Component diese Datei importierte, brach next build mit einer Fehlermeldung ab, dass server-only nicht aus einem Client-Component-Modul importiert werden kann.

// lib/solver.ts
import "server-only";
import { CapSkip } from "capskip";

let client: CapSkip | undefined;

function getClient(): CapSkip {
  const host = process.env.CAPSKIP_HOST;
  // Without this check the SDK would quietly use 127.0.0.1, which on a
  // hosted platform is the platform's own machine.
  if (!host) throw new Error("CAPSKIP_HOST is not set");
  client ??= new CapSkip({
    host,
    port: Number(process.env.CAPSKIP_PORT ?? 8080),
    apiKey: process.env.CAPSKIP_API_KEY, // only matters with API Key Validation on
  });
  return client;
}

// timeout is in seconds and covers this one call; see the timing section.
export async function solveTurnstile(sitekey: string, url: string) {
  const result = await getClient().turnstile(sitekey, url, { timeout: 40 });
  return { token: String(result.code), userAgent: result.userAgent };
}

Das Paket liefert eigene Typdefinitionen mit, daher ist kein @types-Paket nötig, und tsc meldete für die Dateien in diesem Leitfaden mit eingeschaltetem strict-Flag keine Fehler (TypeScript 7.0.2; die tsconfig.json, die Next.js erzeugt, lässt strict ausgeschaltet). Das Feld code ist als String oder Objekt typisiert, weil manche Typen ein Objekt zurückgeben, deshalb verpackt der Helper es in String(). Das optionale Feld userAgent ist laut Paket der User-Agent, den Sie beim Absenden des Tokens verwenden sollen.

Schritt 3: Der Route Handler für Ihren Next.js-Captcha-Solve

Das SDK spricht mit CapSkip über das Node.js-Modul http, daher muss die Route auf der Node.js-Runtime laufen. Laut Next.js-Dokumentation ist nodejs der Standard und edge als veraltet markiert, und der Handler nennt trotzdem nodejs. Bei aktivierten Cache Components sagt die Dokumentation, dass der Export runtime entfernt werden soll, da Node.js dann die einzige Runtime ist; das habe ich nicht getestet. Ich habe auf edge umgestellt, um zu sehen, was passiert: Der Build lief mit einer Veraltet-Warnung durch, und die erste Anfrage antwortete mit 502 und der Meldung, dass die Edge runtime das Node.js-Modul url nicht unterstützt. Das SDK verpackt den Fehler in seine Netzwerk-Exception, deshalb sieht es aus wie ein nicht erreichbares CapSkip.

Die Route ist eine öffentliche URL, die Ihren Solver beansprucht, daher löst sie nur die Seiten einer Allowlist und nur für einen Aufrufer, der Ihr Secret sendet. Sie lehnt ab, wenn SOLVE_SECRET nicht gesetzt ist, denn ein Vergleich mit einem Header Bearer undefined ließe jeden herein, der diesen Header sendet; dieser Header bekam in meinem Lauf ein 401. Object.hasOwn verhindert, dass Namen wie constructor oder toString als Ziele durchgehen; fünf solche Namen und ein JSON-Body null bekamen alle ein 400.

// app/api/turnstile/route.ts
import { timingSafeEqual } from "node:crypto";
import { NextResponse } from "next/server";
import { ApiException, NetworkException, TimeoutException } from "capskip";
import { solveTurnstile } from "../../../lib/solver";

export const runtime = "nodejs"; // the SDK uses node:http, so no Edge
export const maxDuration = 60; // seconds; read by the host platform

// Only these pages can be solved, and only for a caller with the secret.
const TARGETS: Record<string, { sitekey: string; url: string }> = {
  signup: { sitekey: "YOUR_SITEKEY", url: "https://example.com/signup" },
};

function authorized(header: string | null): boolean {
  const secret = process.env.SOLVE_SECRET;
  if (!secret || !header) return false;
  const given = Buffer.from(header);
  const wanted = Buffer.from(`Bearer ${secret}`);
  return given.length === wanted.length && timingSafeEqual(given, wanted);
}

export async function POST(request: Request) {
  if (!authorized(request.headers.get("authorization"))) {
    return NextResponse.json({ error: "unauthorized" }, { status: 401 });
  }
  const body = await request.json().catch(() => null);
  const name = typeof body?.target === "string" ? body.target : "";
  const target = Object.hasOwn(TARGETS, name) ? TARGETS[name] : undefined;
  if (!target) return NextResponse.json({ error: "unknown target" }, { status: 400 });

  try {
    const { token, userAgent } = await solveTurnstile(target.sitekey, target.url);
    return NextResponse.json({ token, userAgent });
  } catch (err) {
    if (err instanceof TimeoutException) {
      return NextResponse.json({ error: "solve timed out" }, { status: 504 });
    }
    if (err instanceof ApiException || err instanceof NetworkException) {
      return NextResponse.json({ error: err.message }, { status: 502 });
    }
    throw err; // a ValidationException is a bug in your code: let it be a 500
  }
}

Eine ApiException enthält die eigene Antwort von CapSkip, etwa ERROR_CAPTCHA_UNSOLVABLE, und ein neuer Versuch kann dabei helfen, wie die ERROR_CAPTCHA_UNSOLVABLE-Anleitung erklärt. Bevor Sie sie ausführen, ersetzen Sie YOUR_SITEKEY und die URL in TARGETS durch den sitekey und die Seite der Website, die Sie automatisieren, und tun Sie dasselbe für PAGE_URL und den sitekey in app/actions.ts weiter unten. Starten Sie den Dev-Server in einem Terminal:

# first terminal, in the project folder
npx next dev

Rufen Sie dann die Route aus einem zweiten Terminal auf, mit Ihrem Secret aus .env.local:

# second terminal
Invoke-RestMethod -Method Post -Uri http://localhost:3000/api/turnstile `
  -Headers @{ Authorization = "Bearer YOUR_LONG_RANDOM_STRING" } `
  -ContentType "application/json" -Body '{"target":"signup"}'

Die Antwort enthält token und userAgent. Setzen Sie den Token in das Formularfeld der Seite, hier cf-turnstile-response, und senden Sie diesen User-Agent mit dem Formular. Meine Mock-Seite akzeptierte einen Token einmal und antwortete beim zweiten Mal mit 403, das ist die Regel des Mocks, nicht die von Cloudflare. Ich habe den Ablauf in next dev sowie in next build plus next start auf beiden Node.js-Versionen ausgeführt. Der erste Lauf schreibt außerdem eine tsconfig.json, und next dev ergänzt eine Datei AGENTS.md; beide stammen von Next.js.

Schritt 4: Oder in einer Server Action lösen und absenden

Braucht der Browser den Token nie, lösen und senden Sie auf dem Server und schicken nur das Ergebnis zurück. Eine Server Action kann das, und der Token bleibt aus dem Browser heraus. Sie importiert denselben Helper und fügt einen Referer hinzu, weil fetch keinen sendet und manche Frameworks ihn beim Absenden eines HTTPS-Formulars prüfen. Außerdem prüft sie zuerst ein Cookie, aus dem Grund, der nach der Seitendatei genannt wird.

// app/actions.ts
"use server";
import { cookies } from "next/headers";
import { solveTurnstile } from "../lib/solver";

const PAGE_URL = "https://example.com/signup";

// Solve and submit in one server-side step, so the token never leaves the server.
export async function signUp(_previous: string, formData: FormData): Promise<string> {
  // A server action is a public endpoint: replace this cookie test with
  // your own session check.
  const secret = process.env.SOLVE_SECRET;
  if (!secret || (await cookies()).get("solve-key")?.value !== secret) return "not allowed";

  const { token, userAgent } = await solveTurnstile("YOUR_SITEKEY", PAGE_URL);
  const reply = await fetch(PAGE_URL, {
    method: "POST",
    headers: {
      Referer: PAGE_URL, // fetch sends no Referer by itself
      ...(userAgent ? { "User-Agent": userAgent } : {}),
    },
    body: new URLSearchParams({
      email: String(formData.get("email")),
      "cf-turnstile-response": token,
    }),
  });
  return `${reply.status} ${(await reply.text()).slice(0, 60)}`;
}

Eine kleine Client Component führt die Action aus, und die Seite exportiert maxDuration aus demselben Grund wie die Route.

// app/signup-form.tsx
"use client";
import { useActionState } from "react";
import { signUp } from "./actions";

export default function SignupForm() {
  const [result, action, pending] = useActionState(signUp, "");
  return (
    <form action={action}>
      <input name="email" defaultValue="[email protected]" />
      <button disabled={pending}>{pending ? "Solving..." : "Sign up"}</button>
      <p id="result">{result}</p>
    </form>
  );
}
// app/page.tsx
import SignupForm from "./signup-form";

export const maxDuration = 60; // meant for the form's server action; unchecked on hosts

export default function Home() {
  return <SignupForm />;
}

Eine Server Action ist ein öffentlicher POST-Endpunkt. Jeder, der diese Seite laden kann, kann sie auslösen. Stellen Sie die Seite hinter Ihre eigene Anmeldung oder prüfen Sie am Anfang von signUp() eine Session oder ein Secret, wie es der Cookie-Test tut. Zum Ausprobieren fügen Sie in den Entwicklertools des Browsers ein Cookie namens solve-key mit Ihrem Secret hinzu. Ohne Prüfung bekam ein Skript, das die versteckten Formularfelder der Seite ohne Zugangsdaten erneut sendete, den Erfolgstext und startete auf dem Mock einen Task.

Mit gesetztem Cookie zeigte ein Klick auf den Button den Willkommenstext der Mock-Seite, und der Token erreichte den Browser nie. Ich konnte nicht prüfen, wie eine Hosting-Plattform maxDuration auf eine Action anwendet, testen Sie das also auf Ihrer.

maxDuration gegen den SDK-Timeout

Die Next.js-Dokumentation zu Route Segments gibt maxDuration einen Standardwert, den die Deployment-Plattform festlegt, und beim Self-Hosting wird er nicht durchgesetzt: Mit maxDuration 2 und einem Mock, der 5 Sekunden brauchte, antwortete next start nach 7,8 Sekunden mit 200 (Node.js 24.22.0). Das Limit, das einen Solve abbricht, setzt Ihr Host. Die Vercel-Dokumentation zur Laufzeit nennt bei aktiviertem Fluid compute einen Standardwert von 300 Sekunden für jeden Plan und ein Maximum von 300 bei Hobby und 800 bei Pro und Enterprise und sagt, dass ein längerer Lauf beendet wird. Exportieren Sie einen selbst gewählten Wert und prüfen Sie die Zahlen Ihrer Plattform; das erweiterte Maximum von 30 Minuten, das sie als Beta aufführt, wird hier nicht behandelt.

Das SDK fragt nach einem Zeitplan ab: Gegen den Mock holte es das Ergebnis bei etwa 0; 0,25; 0,77; 1,78; 3,8; 7,8 und 12,8 Sekunden ab, danach alle 5 Sekunden. Es prüft seine Frist nur, wenn die nächste Abfrage fällig ist. Bei einem Mock, der nie antwortete, endete timeout 5 nach 7,80 Sekunden, timeout 10 nach 12,83 und der timeout 40 der Route nach 42,88 Sekunden, als der Handler sein 504 zurückgab (Node.js 24.22.0 und 20.11.1 stimmten auf 0,1 Sekunden überein). Ein Aufruf kann seinen Timeout also um bis zu 5 Sekunden überschreiten. Halten Sie timeout mindestens 10 Sekunden unter maxDuration, so wie 40 hier unter 60 liegt.

Die Typkommentare des Pakets sagen, Turnstile warte 300 Sekunden, aber in der Quelle von 1.7.0 übergibt turnstile() keinen Timeout, und ein Aufruf ohne die Option endete nach 122,98 Sekunden, es galt also der Standard von 120 Sekunden. Übergeben Sie Ihren eigenen Wert, dann spielt der Widerspruch keine Rolle mehr.

Ein Client, der aufgibt, stoppt den Task nicht. Das SDK kann einen Aufruf nicht abbrechen: Als mein Client die Anfrage nach 1 Sekunde verwarf, fragte der Handler weiter ab, bis zu seiner letzten Abfrage bei 37,9 Sekunden. Halten Sie den Timeout also kurz.

Hosting-Plattformen: CapSkip über den Server-Modus erreichen

Auf einer Hosting-Plattform ist 127.0.0.1 die eigene Maschine der Funktion, nicht Ihr PC. Ich richtete den Handler auf einen Port, an dem nichts lauschte, und bekam nach 0,06 Sekunden ein 502 mit der Meldung connect ECONNREFUSED 127.0.0.1 und dem Port. Eine deployte Funktion sollte dieselbe Meldung für CapSkip auf Ihrem PC zeigen; ich habe nichts deployt, um das zu prüfen.

Die Lösung ist der Server-Modus: In den Verbindungseinstellungen kann CapSkip auch Verbindungen von anderen Geräten in Ihrem Netzwerk oder aus dem Internet auf einem VPS annehmen. Dafür muss CapSkip als Administrator laufen, und laut Anleitung bietet eine statische öffentliche IP den stabilsten Fernzugriff. Setzen Sie dann CAPSKIP_HOST in den Umgebungsvariablen Ihres Hosts auf diese Adresse und CAPSKIP_PORT auf den Port. Die Einstellungen finden Sie in den Verbindungseinstellungen der Einrichtungsanleitung. Gegen einen Mock, der auf allen Adressen lauschte, erreichte der Handler ihn über die Netzwerkadresse meines PCs. Das prüft diese Einstellungen, nicht den echten Server-Modus.

CapSkip öffnet seinen Port für jede Adresse, sobald der Server-Modus startet. Um ihn auf die erwarteten Rechner zu beschränken, fügen Sie für alle anderen eine Blockregel der Windows-Firewall hinzu. Die Egress-Adressen einer Hosting-Plattform lassen sich meist nicht auflisten, daher ist der realistische Schutz dort die API Key Validation, bei der nur Anfragen mit einem Ihrer Schlüssel verarbeitet werden, plus ein kurzer Timeout. Das SDK baut eine einfache http-Adresse, der Schlüssel wird also unverschlüsselt übertragen. Bietet Ihre Plattform feste Egress-Adressen (ich habe keine geprüft), erlauben Sie nur diese und behalten Sie die Blockregel für alles andere. Bei eingeschalteter Validierung und ohne passenden Schlüssel gab meine Route 502 zurück.

Häufige Fehler

Was Sie sehenUrsacheBeheben
Build bricht ab: module format CommonJs does not matchnpm init hat für type den Wert commonjs geschriebenFühren Sie die Zeile npm pkg delete type aus Schritt 1 aus
Build bricht ab: server-only cannot be imported from a Client ComponentEine Datei mit use client importiert den HelperRufen Sie stattdessen die Route oder eine Server Action vom Client aus auf
401 unauthorizedFehlender oder falscher Header Authorization, oder SOLVE_SECRET nicht gesetztSenden Sie Bearer und Ihr Secret
400 unknown targetDer Body enthält keinen Schlüssel aus der AllowlistSenden Sie den Zielnamen, zum Beispiel signup
500 und CAPSKIP_HOST is not set im Server-LogDie Variable ist leer oder nicht gesetzt, wo der Server läuftSetzen Sie sie, dann neu starten oder neu deployen
502 mit ECONNREFUSEDAn diesem Host und Port lauscht nichts, oder Sie sind mit 127.0.0.1 auf einer Hosting-PlattformStarten Sie CapSkip oder nutzen Sie den Server-Modus
502 mit der Meldung, dass die Edge runtime ein Node.js-Modul nicht unterstütztDie Route läuft auf der Edge runtimeExportieren Sie runtime als nodejs
502 mit ERROR_KEY_DOES_NOT_EXISTAPI Key Validation ist eingeschaltet, und der Schlüssel steht nicht in der Liste von CapSkipFügen Sie den Schlüssel in CapSkip hinzu und setzen Sie CAPSKIP_API_KEY
502 mit ERROR_CAPTCHA_UNSOLVABLECapSkip hat es versucht und die Challenge nicht bestandenFragen Sie erneut an, siehe die in Schritt 3 verlinkte Anleitung
504 solve timed outKein Token innerhalb des TimeoutsPrüfen Sie, ob CapSkip läuft, und versuchen Sie es dann erneut
Die Seite lehnt einen Token beim zweiten Mal abEin Token ist nur einmal gültig (eine Regel meiner Mock-Seite)Ein Token pro Absendung

Jede Zeile außer ERROR_CAPTCHA_UNSOLVABLE stammt aus meinen Läufen; diese folgt den CapSkip-Dokumenten.

FAQ

Kann eine Next.js-App auf Vercel ein CapSkip auf meinem PC nutzen?

Ja, über den Server-Modus. CapSkip lauscht auf Ihrem Netzwerk oder Ihrer öffentlichen IP, die Funktion nutzt dieselbe HTTP-API wie lokal, und nur CAPSKIP_HOST ändert sich. Fügen Sie eine Blockregel der Windows-Firewall für Rechner hinzu, die Sie nicht erwarten, und schalten Sie die API Key Validation ein.

Soll die Route den Token an den Browser zurückgeben?

Nur wenn der Browser ihn braucht. Eine Server Action ist für den Token sicherer, weil er dann nie den Browser erreicht, aber nicht für den Endpunkt: Er ist ebenfalls öffentlich, sichern Sie ihn also auch ab. Wofür Sie sich auch entscheiden: Jeder Aufruf startet einen Task auf Ihrem PC.

Berechnet CapSkip pro Lösung, wenn eine Next.js-Route es aufruft?

Nein. Woher die Anfrage auch kommt, der Solver ist weiterhin Ihr eigener Windows-Rechner, ohne Zähler pro Lösung. Ihr Host berechnet möglicherweise die Zeit, die eine Funktion auf ein Ergebnis wartet.

Ein Next.js-Captcha-Solve läuft auf vier Einstellungen hinaus: die Node.js-Runtime, eine maxDuration über dem Timeout, Secrets ohne Namen mit NEXT_PUBLIC_ und eine CapSkip-Adresse, die der Server erreichen kann. Weil das Lösen in einem Captcha-Löser auf Ihrem eigenen PC stattfindet, kostet ein erneuter Versuch nichts extra. Weitere Captcha-Typen finden Sie auf der Node.js-Captcha-Solver-Seite. Zu einem Host mit eigenen Limits, etwa Netlify, lesen Sie die Netlify-Functions-Anleitung.