Next.js 验证码:在 Route Handler 中识别(Node.js SDK)

要在服务器端代码里识别 Next.js 验证码,就在运行于 Node.js runtime 的 App Router Route Handler 中调用 CapSkip,然后返回 token,或在同一个请求里直接使用它。本指南面向这样的开发者:你的 Next.js 服务器要通过一个不属于你的页面上的验证码,而不是给自己的网站添加验证码。处理程序向 capskip 1.7.0 包请求 Cloudflare Turnstile token,把密钥留在服务器上,并设置一个符合函数时限的超时。每个任务都交给 CapSkip Turnstile 识别工具,它运行在你自己拥有的 Windows PC 上,每次识别不收任何费用。
你需要什么
- 一台运行着 CapSkip 的 Windows PC。Local mode 默认监听 127.0.0.1 的 8080 端口。安装步骤见 设置指南.
- Node.js 20.9 或更高版本,这是 Next.js 16.4.6 的 engines 字段规定的下限。capskip 包本身声明的是 Node.js 18。我用的是 20.11.1 和 24.22.0,npm 为 11.19.1。
- 一个带有 Turnstile 小组件、你有权自动化操作的页面,它的 URL,以及小组件 data-sitekey 属性里的 sitekey。
- 一个 Next.js 服务器能够访问的 CapSkip 地址:在你自己的 PC 上是 127.0.0.1,在托管平台上则要用 Server mode。
这里所有内容都是针对我写的两个 mock 运行的:一个模拟 CapSkip 的 in.php 和 res.php 端点,另一个模拟会校验 Turnstile token 的注册页。真正的 CapSkip 应用没有收到任何任务,所以下面的识别耗时都不是真实数据,也没有部署到任何托管平台。选 Turnstile 作示例,是因为它的调用只需要 sitekey 和页面 URL;该包能识别的其他类型都可以套用同一个辅助函数。
第 1 步:创建项目,并把密钥留在服务器端
在一个空文件夹里用 Windows PowerShell 运行下面的命令。删除 type 字段的那一行是必需的:npm 11.19.1 会写入值为 commonjs 的 type,而 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 包。开启 strict 标志后,tsc 对本指南中的文件没有报告任何错误(TypeScript 7.0.2;Next.js 生成的 tsconfig.json 把 strict 关着)。code 字段的类型是字符串或对象,因为有些类型返回的是对象,所以辅助函数用 String() 把它包起来。可选的 userAgent 字段,按该包的说明,是提交 token 时要使用的 User-Agent。
第 3 步:用于识别 Next.js 验证码的 Route Handler
SDK 通过 Node.js 的 http 模块与 CapSkip 通信,所以这个路由必须运行在 Node.js runtime 上。Next.js 文档把 nodejs 作为默认值,并把 edge 标为已弃用,但处理程序里仍然明确写了 nodejs。启用 Cache Components 后,文档说要删掉 runtime 导出,因为那时 Node.js 是唯一的 runtime;这一点我没有测试。我把它改成 edge 看会怎样:构建通过并给出弃用警告,第一个请求返回 502,消息是 Edge runtime 不支持 Node.js 的 url 模块。SDK 把这个失败包装成它的网络异常,所以看起来像是 CapSkip 无法访问。
这个路由是一个公开 URL,会消耗你的识别能力,所以它只识别白名单里的页面,并且只接受发送了你的密钥的调用方。SOLVE_SECRET 未设置时它会拒绝请求,因为拿一个 Bearer undefined 的请求头去比较,会放行任何发送该请求头的人;在我的运行中,这个请求头得到了 401。Object.hasOwn 能防止 constructor 或 toString 这类名称被当作目标放行;五个这样的名称以及一个值为 null 的 JSON 请求体,都得到了 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 指南 。运行之前,把 TARGETS 里的 YOUR_SITEKEY 和 URL 换成你要自动化的网站的 sitekey 和页面,并对后面 app/actions.ts 里的 PAGE_URL 和 sitekey 做同样的替换。在一个终端里启动开发服务器:
# 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。把 token 填进页面的表单字段,这里是 cf-turnstile-response,并在提交表单时带上那个 User-Agent。我的 mock 网站对同一个 token 只接受一次,第二次返回 403,这是 mock 自己的规则,不是 Cloudflare 的规则。我在 next dev 里,以及在 next build 加 next start 里,用两个 Node.js 版本都跑了这个流程。第一次运行还会写入一个 tsconfig.json,next dev 会添加一个 AGENTS.md 文件,两者都来自 Next.js。
第 4 步:或者在 server action 里识别并提交
如果浏览器根本不需要 token,就在服务器上识别并提交,只把结果送回去。server action 可以做到这一点,token 不会出现在浏览器里。它导入同一个辅助函数,并加上 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 负责运行这个 action,页面导出 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 端点。任何能加载这个页面的人都能触发它。把页面放在你自己的登录之后,或者像 cookie 检查那样,在 signUp() 开头检查会话或密钥。要试用的话,在浏览器开发者工具里添加一个名为 solve-key 的 cookie,值为你的密钥。没有检查时,一个不带任何凭据、只是重放页面隐藏表单字段的脚本,得到了成功文本,并在 mock 上启动了一个任务。
设置好 cookie 后,点击按钮会显示 mock 网站的欢迎文本,token 从未到达浏览器。我没法验证托管平台如何对 action 应用 maxDuration,所以请在你的平台上自行测试。
maxDuration 与 SDK 超时的关系
Next.js 路由段文档 说明 maxDuration 的默认值由部署平台设定,自托管时并不强制执行:maxDuration 设为 2、mock 需要 5 秒时,next start 在 7.8 秒后返回了 200(Node.js 24.22.0)。真正切断识别的是你的托管平台的限制。 Vercel 时长文档 列出:开启 Fluid compute 时,所有套餐的默认值是 300 秒,Hobby 的最大值是 300 秒,Pro 和 Enterprise 是 800 秒,并说明超时的运行会被终止。请导出一个你选定的值,并核对你所用平台的数字;它列为 beta 的 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 至少比 maxDuration 小 10 秒,就像这里 40 比 60 小一样。
该包的类型注释说 Turnstile 等待 300 秒,但在 1.7.0 的源码里,turnstile() 没有传入 timeout,不带该选项的调用在 122.98 秒后结束,所以生效的是 120 秒的默认值。传入你自己的值,这个不一致就不再有影响。
客户端放弃并不会停止任务。SDK 无法取消调用:我的客户端在 1 秒后断开请求,处理程序仍然一直轮询到 37.9 秒时的最后一次轮询。所以请把 timeout 设短一些。
托管平台:用 Server mode 连接 CapSkip
在托管平台上,127.0.0.1 是函数自己所在的机器,不是你的 PC。我把处理程序指向一个没有任何程序监听的端口,0.06 秒后得到 502,消息是 connect ECONNREFUSED 127.0.0.1 加上端口。对于你 PC 上的 CapSkip,已部署的函数应该会显示同样的消息;我没有部署任何东西来验证。
解决办法是 Server mode:在连接设置里,CapSkip 还可以接受来自你网络中其他设备的连接,或者在 VPS 上接受来自互联网的连接。这需要 CapSkip 以管理员身份运行,而且指南说固定的公网 IP 能提供最稳定的远程访问。然后在你的托管平台的环境变量里,把 CAPSKIP_HOST 设为该地址,把 CAPSKIP_PORT 设为端口。这些设置见 设置指南中的连接设置。针对一个监听所有地址的 mock,处理程序通过我的 PC 的网络地址连上了它。这验证的是这些设置,而不是真正的 Server mode。
Server mode 启动时,CapSkip 会向所有地址开放它的端口,所以为了只允许你预期的机器访问,请为其他地址添加一条 Windows Firewall 阻止规则。托管平台的出口地址通常无法列出,所以在那里切实可行的保护是 API Key Validation,即只处理携带你的某个密钥的请求,再加上较短的 timeout。SDK 构建的是普通的 http 地址,所以密钥是未加密传输的。如果你的平台提供固定的出口地址(我没有检查过任何一家),就只允许这些地址,并保留阻止规则来拦截其余所有地址。打开校验且密钥不匹配时,我的路由返回了 502。
常见错误
| 你所看到的 | 原因 | 修复 |
|---|---|---|
| 构建中止:module format CommonJs does not match | npm init 写入了值为 commonjs 的 type | 运行第 1 步中的 npm pkg delete type 那一行 |
| 构建中止:server-only cannot be imported from a 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 runtime 不支持某个 Node.js 模块 | 路由运行在 Edge runtime 上 | 把 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 | 在 timeout 内没有拿到 token | 检查 CapSkip 是否在运行,然后重试 |
| 页面第二次拒绝该 token | token 只能使用一次(这是我的 mock 网站的规则) | 每次提交一个 token |
除 ERROR_CAPTCHA_UNSOLVABLE 外,每一行都来自我自己的运行;那一行依据的是 CapSkip 文档。
常见问题
Vercel 上的 Next.js 应用能使用我 PC 上的 CapSkip 吗?
可以,通过 Server mode。CapSkip 监听你的网络或公网 IP,函数使用与本地相同的 HTTP API,只有 CAPSKIP_HOST 需要改。为你不预期的机器添加一条 Windows Firewall 阻止规则,并打开 API Key Validation。
路由应该把 token 返回给浏览器吗?
只有浏览器需要它时才返回。server action 对 token 更安全,因为那样 token 根本不会到达浏览器,但对端点本身并不更安全:它同样是公开的,所以也要加上保护。无论选哪种,每次调用都会在你的 PC 上启动一个任务。
CapSkip 在 Next.js 路由调用它时会按次计费吗?
不会。无论请求从哪里来,识别工作仍然由你自己的 Windows 机器完成,上面没有按次计费的计量。你的托管平台可能会对函数等待结果的时间计费。
Next.js 验证码的识别归结为四项设置:Node.js runtime,高于 timeout 的 maxDuration,名称不带 NEXT_PUBLIC_ 的密钥,以及服务器能够访问的 CapSkip 地址。因为识别工作是由你自己 PC 上的 验证码识别工具 完成的,所以重试不会产生额外费用。其他验证码类型见 Node.js 验证码识别页面。像 Netlify 这样自带限制的托管平台,见 Netlify Functions 指南.
