Решение капчи в Next.js: Route Handler (Node.js SDK)

Чтобы решить капчу в Next.js из серверного кода, вызовите CapSkip внутри Route Handler в App Router, который работает в среде Node.js, и затем верните токен или используйте его в том же запросе. Это руководство для разработчика, чей сервер Next.js должен пройти капчу на чужой странице, а не для добавления капчи на ваш собственный сайт. Обработчик просит у пакета capskip 1.7.0 токен Cloudflare Turnstile, хранит секреты на сервере и задаёт таймаут, который укладывается в лимит функции. Каждое задание уходит на вход решателя CapSkip для Turnstile, который работает на принадлежащем вам ПК с Windows и не берёт ничего за решение.
Что понадобится
- ПК с Windows и запущенным CapSkip. Local mode по умолчанию слушает 127.0.0.1, порт 8080. Шаги установки описывает руководство по настройке.
- Node.js 20.9 или новее: это нижняя граница в поле engines у Next.js 16.4.6. Сам пакет capskip заявляет Node.js 18. Я запускал 20.11.1 и 24.22.0 с npm 11.19.1.
- Страница с виджетом Turnstile, которую вам разрешено автоматизировать, её URL и sitekey из атрибута data-sitekey виджета.
- Адрес CapSkip, до которого может дотянуться ваш сервер Next.js: 127.0.0.1 на вашем собственном ПК, Server mode на хостинг-платформе.
Всё здесь запускалось против двух mock-серверов, которые я написал: один изображает конечные точки CapSkip in.php и res.php, другой изображает страницу регистрации, проверяющую токен Turnstile. Настоящему приложению CapSkip задание не отправлялось, поэтому ни одно время решения ниже не настоящее, и на хостинг-платформу ничего не выкладывалось. Turnstile взят как пример, потому что для его вызова нужны только sitekey и URL страницы; любой другой тип, который решает пакет, подходит к тому же помощнику.
Шаг 1: создайте проект и держите секреты на стороне сервера
Выполните это в пустой папке в Windows PowerShell. Строка, удаляющая поле type, нужна: npm 11.19.1 записывает type со значением commonjs, и тогда Next.js 16.4.6 отказывался собирать проект.
# 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
Создайте в этой папке файл .env.local. Next.js загружает его для next dev и next start. Ни одно имя не начинается с NEXT_PUBLIC_, и это важно: Next.js подставляет значение такой переменной вместо обращения к ней в браузерном коде во время сборки. Я собрал проект с одной такой переменной, к которой обращался Client Component, и её значение попало в файл в .next/static. Переменная с префиксом, к которой никто не обращался, и переменная без префикса не попали ни в один файл там.
# .env.local CAPSKIP_HOST=127.0.0.1 CAPSKIP_PORT=8080 CAPSKIP_API_KEY=YOUR_API_KEY SOLVE_SECRET=YOUR_LONG_RANDOM_STRING
Когда API Key Validation выключена, CapSkip принимает любое значение ключа, поэтому строка с ключом важна, только когда вы включите проверку. SOLVE_SECRET служит паролем для вашего собственного маршрута (Шаг 3). Next.js также нужен корневой layout:
// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>{children}</body>
</html>
);
}Шаг 2: один помощник, который общается с CapSkip
Держите SDK в одном файле, который может импортировать только сервер. Его первая строка, импорт server-only, превращает ошибку в сбой сборки. Когда этот файл импортировал Client Component, next build останавливался с ошибкой о том, что server-only нельзя импортировать из модуля Client Component.
// 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 };
}Пакет поставляется со своими определениями типов, поэтому пакет @types не нужен, и tsc не сообщил об ошибках для файлов этого руководства при включённом флаге strict (TypeScript 7.0.2; сгенерированный Next.js tsconfig.json оставляет strict выключенным). Поле code типизировано как строка или объект, потому что некоторые типы возвращают объект, поэтому помощник оборачивает его в String(). Необязательное поле userAgent по описанию пакета содержит User-Agent, который нужно использовать при отправке токена.
Шаг 3: Route Handler для решения капчи в Next.js
SDK обращается к CapSkip через модуль http из Node.js, поэтому маршрут должен работать в среде Node.js. В документации Next.js nodejs указан по умолчанию, а edge помечен как устаревший, и всё же обработчик явно указывает nodejs. Если включены Cache Components, документация советует убрать экспорт runtime, поскольку тогда Node.js остаётся единственной средой; это я не проверял. Я переключил его на edge, чтобы посмотреть, что будет: сборка прошла с предупреждением об устаревании, а первый запрос получил ответ 502 с сообщением о том, что среда Edge не поддерживает модуль url из Node.js. SDK оборачивает этот сбой в своё сетевое исключение, поэтому он выглядит как недоступный CapSkip.
Маршрут представляет собой публичный URL, который тратит ваш решатель, поэтому он решает только страницы из списка разрешённых и только для вызывающего, который присылает ваш секрет. Он отказывает, если SOLVE_SECRET не задан, потому что сравнение с заголовком Bearer undefined пропустило бы любого, кто пришлёт такой заголовок; в моём запуске этот заголовок получил 401. Object.hasOwn не даёт именам вроде constructor или toString сойти за цели; пять таких имён и JSON-тело null получили 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
}
}ApiException несёт собственный ответ CapSkip, например ERROR_CAPTCHA_UNSOLVABLE. Про такой случай рассказывает руководство по ERROR_CAPTCHA_UNSOLVABLE и объясняет, когда помогает новый запрос. Перед запуском замените YOUR_SITEKEY и URL в TARGETS на sitekey и страницу сайта, который вы автоматизируете, и сделайте то же для PAGE_URL и sitekey в app/actions.ts ниже. Запустите сервер разработки в одном терминале:
# first terminal, in the project folder npx next dev
Затем вызовите маршрут из второго терминала, подставив ваш секрет из .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"}'Ответ содержит token и userAgent. Подставьте токен в поле формы страницы, здесь это cf-turnstile-response, и отправьте вместе с формой этот User-Agent. Мой mock-сайт принял токен один раз, а во второй ответил 403: это правило mock-сайта, а не Cloudflare. Я прогнал весь процесс в next dev и в next build плюс next start, на обеих версиях Node.js. При первом запуске также создаётся tsconfig.json, а next dev добавляет файл AGENTS.md; оба появляются от Next.js.
Шаг 4: или решайте и отправляйте в server action
Если браузеру токен не нужен, решайте и отправляйте на сервере и возвращайте только результат. Это умеет server action, и токен не попадает в браузер. Он импортирует того же помощника и добавляет Referer, потому что fetch его не отправляет, а некоторые фреймворки проверяют его при отправке формы по HTTPS. Сначала он также проверяет cookie, по причине, которая названа после файла страницы.
// 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)}`;
}Небольшой Client Component запускает действие, а страница экспортирует maxDuration по той же причине, что и маршрут.
// 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 />;
}Server action является публичной конечной точкой POST. Запустить её может любой, кто может загрузить эту страницу. Закройте страницу вашим собственным входом или проверьте сессию или секрет в начале signUp(), как это делает проверка cookie. Чтобы попробовать, добавьте в инструментах разработчика браузера cookie с именем solve-key, содержащую ваш секрет. Без проверки скрипт, воспроизводивший скрытые поля формы страницы без учётных данных, получил текст об успехе и запустил задание на mock-сервере.
С установленной cookie клик по кнопке показал приветственный текст mock-сайта, и токен не дошёл до браузера. Я не смог проверить, как хостинг-платформа применяет maxDuration к действию, поэтому проверьте это на своей.
maxDuration и таймаут SDK
Документация Next.js по сегментам маршрута задаёт для maxDuration значение по умолчанию, которое определяет платформа развёртывания, а при самостоятельном хостинге оно не применяется: при maxDuration равном 2 и mock, которому нужно было 5 секунд, next start ответил 200 через 7,8 секунды (Node.js 24.22.0). Лимит, обрывающий решение, задаёт ваш хостинг. Документация Vercel по длительности указывает при включённом Fluid compute значение по умолчанию 300 секунд на всех тарифах и максимум 300 на Hobby и 800 на Pro и Enterprise, а более долгий запуск завершается. Экспортируйте выбранное вами значение и проверьте цифры своей платформы; расширенный максимум в 30 минут, который там указан как бета, здесь не рассматривается.
SDK опрашивает результат по расписанию: на mock он запрашивал результат примерно на 0, 0,25, 0,77, 1,78, 3,8, 7,8 и 12,8 секунде, затем каждые 5 секунд. Крайний срок он проверяет только тогда, когда подходит время следующего опроса. С mock, который так и не ответил, timeout 5 закончился через 7,80 секунды, timeout 10 через 12,83, а timeout 40 у маршрута через 42,88 секунды, когда обработчик вернул свой 504 (Node.js 24.22.0 и 20.11.1 сошлись с точностью до 0,1 секунды). Так что вызов может превысить свой timeout до 5 секунд. Держите timeout минимум на 10 секунд меньше maxDuration, как здесь 40 меньше 60.
В комментариях к типам пакета сказано, что Turnstile ждёт 300 секунд, но в исходниках 1.7.0 turnstile() не передаёт timeout, и вызов без этой опции закончился на 122,98 секунды, то есть сработало значение по умолчанию в 120 секунд. Передайте собственное значение, и это расхождение перестанет иметь значение.
Клиент, который сдался, не останавливает задание. SDK не умеет отменять вызов: когда мой клиент оборвал запрос через 1 секунду, обработчик продолжал опрос до последнего опроса на 37,9 секунде. Поэтому держите timeout коротким.
Хостинг-платформы: достучитесь до CapSkip через Server mode
На хостинг-платформе 127.0.0.1 указывает на собственную машину функции, а не на ваш ПК. Я направил обработчик на порт, где ничего не слушало, и получил 502 за 0,06 секунды с сообщением connect ECONNREFUSED 127.0.0.1 и портом. Развёрнутая функция должна показать то же сообщение для CapSkip на вашем ПК; я ничего не разворачивал, чтобы проверить это.
Решение такое: Server mode. В настройках подключения CapSkip может также принимать соединения с других устройств в вашей сети или из интернета на VPS. Для этого CapSkip нужно запускать от имени администратора, а руководство говорит, что статический публичный IP даёт самый стабильный удалённый доступ. После этого задайте CAPSKIP_HOST в переменных окружения вашего хостинга равным этому адресу, а CAPSKIP_PORT равным порту. Настройки описаны в настройках подключения из руководства по настройке. С mock, слушавшим на всех адресах, обработчик достучался до него по сетевому адресу моего ПК. Это проверяет эти настройки, а не настоящий Server mode.
CapSkip открывает свой порт для всех адресов, когда запускается Server mode, поэтому чтобы ограничить его ожидаемыми машинами, добавьте для остальных блокирующее правило брандмауэра Windows Firewall. Адреса исходящих запросов хостинг-платформы обычно нельзя перечислить, поэтому реальная защита там такая: API Key Validation, при которой обрабатываются только запросы с одним из ваших ключей, плюс короткий timeout. SDK строит обычный адрес http, поэтому ключ передаётся без шифрования. Если ваша платформа предлагает фиксированные адреса исходящих запросов (я никакие не проверял), разрешите только их и оставьте блокирующее правило для всего остального. При включённой проверке и без подходящего ключа мой маршрут вернул 502.
Частые ошибки
| Что вы видите | Причина | Исправить |
|---|---|---|
| Сборка останавливается: формат модуля CommonJs не соответствует | npm init записал type со значением commonjs | Выполните строку npm pkg delete type из Шага 1 |
| Сборка останавливается: server-only нельзя импортировать из Client Component | Файл с use client импортирует помощника | Вместо этого вызывайте маршрут или server action с клиента |
| 401 unauthorized | Заголовок Authorization отсутствует или неверный, либо SOLVE_SECRET не задан | Отправьте Bearer и ваш секрет |
| 400 unknown target | В теле нет ключа из списка разрешённых | Отправьте имя цели, например signup |
| 500 и CAPSKIP_HOST is not set в журнале сервера | Переменная пуста или не задана там, где работает сервер | Задайте её, затем перезапустите или разверните заново |
| 502 с ECONNREFUSED | По этому хосту и порту никто не слушает, либо вы на хостинг-платформе с 127.0.0.1 | Запустите CapSkip или используйте Server mode |
| 502 с сообщением, что среда Edge не поддерживает модуль Node.js | Маршрут работает в среде Edge | Экспортируйте runtime со значением nodejs |
| 502 с ERROR_KEY_DOES_NOT_EXIST | API Key Validation включена, а ключа нет в списке CapSkip | Добавьте ключ в CapSkip и задайте CAPSKIP_API_KEY |
| 502 с ERROR_CAPTCHA_UNSOLVABLE | CapSkip попробовал, но не прошёл проверку | Повторите запрос, см. руководство, на которое есть ссылка в Шаге 3 |
| 504 solve timed out | Токен не получен за время таймаута | Проверьте, что CapSkip запущен, затем повторите |
| Страница отклоняет токен во второй раз | Токен одноразовый (правило моего mock-сайта) | Один токен на одну отправку |
Каждая строка, кроме ERROR_CAPTCHA_UNSOLVABLE, взята из моих запусков; эта следует документации CapSkip.
FAQ
Может ли приложение Next.js на Vercel использовать CapSkip на моём ПК?
Да, через Server mode. CapSkip слушает вашу сеть или публичный IP, функция использует тот же HTTP API, что и локально, и меняется только CAPSKIP_HOST. Добавьте блокирующее правило брандмауэра Windows Firewall для непредусмотренных машин и включите API Key Validation.
Должен ли маршрут возвращать токен в браузер?
Только если токен нужен браузеру. Server action безопаснее для токена, который тогда не попадает в браузер, но не для самой конечной точки: она тоже публична, поэтому защитите и её. Что бы вы ни выбрали, каждый вызов запускает задание на вашем ПК.
Берёт ли CapSkip плату за каждое решение, когда его вызывает маршрут Next.js?
Нет. Откуда бы ни пришёл запрос, решатель остаётся вашей собственной машиной с Windows, без счётчика платы за решение. Ваш хостинг может тарифицировать время, которое функция проводит в ожидании результата.
Решение капчи в Next.js сводится к четырём настройкам: среда Node.js, maxDuration больше таймаута, секреты без имени NEXT_PUBLIC_ и адрес CapSkip, до которого дотянется сервер. Поскольку выполняется распознавание капчи на вашем собственном ПК, повторная попытка не стоит ничего дополнительно. Другие типы капчи смотрите на странице сервиса распознавания капчи для Node.js. Хост со своими ограничениями, например Netlify, разобран в руководстве по Netlify Functions.
