Electron 验证码:在主进程中识别 Turnstile

要在 Electron 应用里识别验证码,就把这项工作放在主进程中完成。在 BrowserWindow 里加载页面,用 webContents.executeJavaScript 读出 sitekey,通过 capskip Node SDK 向 CapSkip 要一个 token,把窗口切换成识别工具报告的 User-Agent,再把 token 写进隐藏字段并提交表单。这篇 electron captcha 指南写给需要在 Electron 应用内部通过 Turnstile 小组件的开发者,而不是给自己的网站添加小组件的人。渲染进程通过 IPC 请求这项任务,永远看不到 API key。每个 token 都来自 CapSkip Turnstile 识别工具 ,它运行在你自己拥有的 Windows PC 上。
你需要什么
- 一台 Windows PC,已按 设置指南 所述安装好 CapSkip,并以 Local mode 运行,它监听 127.0.0.1:8080。
- Node.js 22.12 或更高版本用于 npm,这是 electron 包声明的下限。capskip 包声明的是 Node.js 18,而 Electron 45.3.0 内置的 Node.js 满足这个要求:它报告的版本是 24.22.2。在我的运行中,第一次启动花了 21.9 秒下载 Electron 程序,npm install 并不会下载它。
- 一个带有 Turnstile 小组件、你有权自动化操作的页面。
- 一个适合应用运行位置的 CapSkip 地址。Local mode 只为它所在的这台 PC 服务,而 Server mode 会监听你的网络或公网 IP,发布出去的应用需要这种方式(见最后一节)。
我选择 Turnstile,是因为它的小组件把 token 保存在一个普通的隐藏 input 里,而且它的结果带有识别工具使用的 User-Agent,但 Electron 页面加载时用的是另一个。这个冲突正是这项工作中属于 Electron 的部分。
所有内容都在 Windows 11 上运行,使用 Electron 45.3.0(Chrome 156.0.8078.96)和 capskip 1.7.0,对着我写的两个模拟服务器:一个扮演 CapSkip,另一个扮演带有 Turnstile 形态小组件的联系页面。token 文本和每条站点规则都是我定的,真实的 CapSkip 应用没有收到任何任务。一个包装脚本启动同一个 main.js,在每个窗口打开时把它隐藏,并用脚本点击按钮;用可见窗口跑了一次,结果一致。我从未打包过这个应用。
第 1 步:两个窗口、一个 preload 脚本和 IPC 桥
新建一个空文件夹,运行下面这三条命令。最后一条让 npm start 从 main.js 启动项目。
# npm install electron capskip npm init -y npm install electron capskip npm pkg set main=main.js
应用需要两个窗口。一个显示你自己的界面,并带有 preload 脚本。另一个加载带 CAPTCHA 的页面,什么都不带,所以那个页面上的脚本没有通向你主进程的桥。我显式设置了 contextIsolation、nodeIntegration 和 sandbox,不过在 Electron 45.3.0 中,没有 webPreferences 的窗口报告的值是一样的,而 Electron 安全指南 说明这些默认值分别从版本 12、5 和 20 起生效。
// main.js
const { app, BrowserWindow, ipcMain } = require("electron");
const { once } = require("node:events");
const path = require("node:path");
const { CapSkip } = require("capskip");
// The page that shows the Turnstile widget.
const SITE_URL = process.env.SITE_URL || "https://example.com/contact";
// The only place that knows the host and the key. Local mode by default.
const solver = new CapSkip({
host: process.env.CAPSKIP_HOST || "127.0.0.1",
port: Number(process.env.CAPSKIP_PORT || 8080),
apiKey: process.env.CAPSKIP_API_KEY || "capskip",
});
let ui;
let site;
let busy = false;
// The page with the CAPTCHA: no preload, so nothing is exposed to it.
function createSite() {
return new BrowserWindow({
width: 900,
height: 700,
webPreferences: { contextIsolation: true, nodeIntegration: false, sandbox: true },
});
}
app.whenReady().then(() => {
// Your own interface: the only window that gets the preload script.
ui = new BrowserWindow({
width: 480,
height: 320,
webPreferences: {
preload: path.join(__dirname, "preload.js"),
contextIsolation: true,
nodeIntegration: false,
sandbox: true,
},
});
ui.loadFile("index.html");
site = createSite();
});
app.on("window-all-closed", () => app.quit());CapSkip 在这里只构建一次,它的主机、端口和密钥来自你自己读取的环境变量,因为 SDK 不读取任何环境变量。preload 只暴露一个函数,绝不暴露整个 ipcRenderer,而 invoke 会以主进程处理程序返回的任何内容完成。
// preload.js
const { contextBridge, ipcRenderer } = require("electron");
// Expose one narrow function, never ipcRenderer itself.
contextBridge.exposeInMainWorld("captcha", {
send: (email) => ipcRenderer.invoke("captcha:send", email),
});界面脚本放在单独的文件里,所以它自己的 Content-Security-Policy 可以只允许来自 self 的脚本,安全指南也是这样建议的。
<!-- index.html --> <!doctype html> <meta charset="utf-8"> <meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self'"> <title>Send with CAPTCHA</title> <input id="email" value="[email protected]"> <button id="go">Solve and send</button> <pre id="out"></pre> <script src="renderer.js"></script>
// renderer.js
const go = document.getElementById("go");
const out = document.getElementById("out");
go.addEventListener("click", async () => {
go.disabled = true;
out.textContent = "Solving";
const reply = await window.captcha.send(document.getElementById("email").value);
out.textContent = JSON.stringify(reply, null, 2);
go.disabled = false;
});在两个窗口里,require 和 process 都是 undefined;window.captcha 在界面窗口里只有一个键 send,在页面窗口里是 undefined;API key 没有出现在任何一个页面的 HTML 里。一个使用相同 preload 但显示另一个页面的探测窗口,被处理程序的发送方检查拒绝并返回了拒绝的回复,Electron 安全指南也要求做这项检查。
第 2 步:识别并提交的处理程序
把下面的代码粘贴到 main.js 第一部分的后面。它加载页面,从小组件的 data-sitekey 属性读出 sitekey,调用 solver.turnstile,采用报告的 User-Agent,填写表单,并等待返回的页面。
// main.js, continued below the first part
// Read the sitekey from the page, solve, set the User-Agent, fill, submit.
async function solveAndSend(email) {
// The user may have closed the page window since the last job.
if (!site || site.isDestroyed()) site = createSite();
await site.loadURL(SITE_URL);
const web = site.webContents;
const sitekey = await web.executeJavaScript(
`document.querySelector("[data-sitekey]")?.dataset.sitekey ?? null`
);
if (!sitekey) return { ok: false, error: "no widget on the page" };
// Turnstile polls on defaultTimeout; this call is capped at 60 seconds.
const solved = await solver.turnstile(sitekey, web.getURL(), { timeout: 60 });
if (web.isDestroyed()) return { ok: false, error: "window closed" };
// Submit with the User-Agent the token was earned with.
if (solved.userAgent) web.setUserAgent(solved.userAgent);
// JSON.stringify keeps a quote in a value from breaking out of the string.
const fill = `(() => {
const form = document.querySelector("form");
form.elements["email"].value = ${JSON.stringify(email)};
let field = form.elements["cf-turnstile-response"];
if (!field) {
field = Object.assign(document.createElement("input"), { type: "hidden", name: "cf-turnstile-response" });
form.appendChild(field);
}
field.value = ${JSON.stringify(solved.code)};
form.requestSubmit();
})()`;
const loaded = once(web, "did-finish-load");
await web.executeJavaScript(fill);
await loaded;
const page = await web.executeJavaScript("document.body.innerText");
return { ok: true, page: page.trim().slice(0, 80) };
}
ipcMain.handle("captcha:send", async (event, email) => {
if (event.sender !== ui.webContents) return { ok: false, error: "refused" };
if (typeof email !== "string" || email.length > 200) {
return { ok: false, error: "bad email" };
}
if (busy) return { ok: false, error: "busy" };
busy = true;
try {
return await solveAndSend(email);
} catch (err) {
// An Error thrown here reaches the renderer as a message only.
return { ok: false, error: err.constructor.name, message: err.message };
} finally {
busy = false;
}
});有四个细节很重要。第一,在 1.7.0 中,Turnstile 的应答包含 captchaId、code 和 userAgent,没有 token 字段,所以 token 就是 code。第二,回复里的 ok 表示表单已提交,而不是站点接受了 token:跳过 User-Agent 步骤时,我的模拟服务器对应用回复了 ok,页面上却显示 Verification failed,所以要去找你自己站点的成功文本。第三,Cloudflare 的 渲染指南 说,隐式渲染会添加一个名为 cf-turnstile-response 的不可见 input,并且 token 300 秒后过期,只能验证一次。如果你的页面在小组件完成时会运行回调,CapSkip API 文档建议带着 token 去运行它;这一点我没有测试。我在一个隐藏窗口里加载过一次 Cloudflare 的真实小组件脚本,使用的是 Cloudflare 公布的测试用 sitekey,加载约 2.5 秒后 input 出现了,所以代码会在字段缺失时创建它。我没有把那个 token 提交到任何地方,也没有测试小组件是否会覆盖你设置的值。第四,JSON.stringify 把这些值构建进脚本,一个含有引号和反斜杠的邮箱原样到达了我的模拟服务器。
时间限制与关闭的窗口
Turnstile 按客户端默认的 120 秒超时轮询,而不是更长的 reCAPTCHA 超时:设置 defaultTimeout 为 5、recaptchaTimeout 为 300 时,一个始终不回答的模拟服务器在 7.8 秒后以 TimeoutException 结束。timeout 选项是按每次调用设置的,单位是秒,我设成了 60。SDK 只在下一次轮询到期时才检查截止时间,所以一个始终不回答的模拟服务器从点击到回复花了 63.0 秒。ipcRenderer.invoke 自己没有超时:一个始终不返回的处理程序,在我观察 20 秒后停止时,调用仍处于挂起状态。SDK 的超时是你唯一的限制。
SDK 无法取消。在一次 4 秒的模拟识别进行到 1.5 秒时,我关闭了页面窗口,SDK 仍在继续轮询,回复在 7.9 秒时才到。没有 isDestroyed 检查时,setUserAgent 会抛出 TypeError: Object has been destroyed,没有 createSite 时,之后的每次点击都会以同样方式失败;两者都有时,下一次点击会打开新的页面窗口并成功。识别期间的第二次点击得到的是 busy 回复,因为一个页面窗口不能同时处理两个任务。
在处理程序内部抛出的 Error 到达渲染进程时只剩下消息:我的探测抛出了带有 code 属性的 MyErr,渲染进程看到的却是普通的 Error。所以处理程序会捕获一切,并返回一个保留 SDK 异常类名和消息的对象。
第 3 步:页面的 Content-Security-Policy 会拦截什么
Electron 关于 executeJavaScript 的文档没有提到 Content-Security-Policy,所以我做了测试。我分别在没有策略和带有 script-src self 策略的情况下加载模拟页面,并在主世界中运行同样的探测。
| 探测项 | 无策略 | 策略 script-src self |
|---|---|---|
| 页面自己的 HTML 中写的内联脚本 | 已运行 | 被阻止 |
| 来自页面同源的脚本文件 | 已运行 | 已运行 |
| executeJavaScript 设置隐藏 input | 成功 | 成功 |
| 在被执行的代码里调用 eval() 或 new Function() | 成功 | EvalError |
| 由被执行的代码添加的、带内联文本的 script 元素 | 已运行 | 被阻止 |
| executeJavaScriptInIsolatedWorld 中的 eval() | 成功 | 成功 |
你交给 executeJavaScript 的代码会运行,但策略仍然适用于它用字符串构建出的任何东西。设置属性并调用现有函数,策略就管不着。第 2 步的完整流程在带 script-src 的页面上通过了,而 default-src none 策略连页面自己的脚本文件也拦截了,却仍然允许设置隐藏 input。
第 4 步:页面加载时使用的 User-Agent
Electron 窗口会用一个 Electron 标记来标识自己:我的模拟服务器看到的是 Chrome/156.0.8078.96 Electron/45.3.0。CapSkip API 文档说,提交 Turnstile token 时要发送识别工具的 User-Agent,而 Node SDK 不允许你选择它:userAgent 和 useragent 都会抛出 ValidationException,提示 Unsupported parameters for Turnstile。处理程序在页面加载之后调用 webContents.setUserAgent;我的模拟服务器记录了五种设置方式的这些结果。
| 设置方式 | navigator.userAgent | 请求头 |
|---|---|---|
| 页面加载后调用 webContents.setUserAgent | 立即改变,无需重新加载 | 下一次提交表单时与识别工具的一致 |
| loadURL 之前调用 webContents.setUserAgent | 与识别工具的一致 | 页面加载和提交时都与识别工具的一致 |
| 自定义 session 上的 session.setUserAgent,或 loadURL 的 userAgent 选项 | 与识别工具的一致 | 两次都与识别工具的一致 |
| webRequest onBeforeSendHeaders 钩子 | 仍是 Electron 字符串 | 两次都与识别工具的一致 |
这个钩子是个例外:读取 navigator.userAgent 的页面脚本看到的仍是 Electron,而服务器看到的却是别的值。应用只有在页面打开之后才知道 User-Agent,所以页面加载后再调用最合适。我的请求里没有一个带有 sec-ch-ua 头,而且调用 setUserAgent 之后,navigator.userAgentData.brands 列表仍然写着 Chromium 156,所以两者并不一致。Chromium 自己给表单提交加上了 Referer 和 Origin。User-Agent 检查是我的模拟服务器定的规则:我没有测试任何真实站点,所以真实站点是否会比较这两者,还没有验证。
运行它,以及发布应用时的 Server mode
设置页面地址,然后启动应用。两行被注释掉的代码只用于 Server mode;只要 CapSkip 运行在同一台 PC 上,就不要动它们。
# Run from the project folder in PowerShell $env:SITE_URL = "https://example.com/contact" # Server mode only: another PC runs CapSkip # $env:CAPSKIP_HOST = "192.168.1.50" # $env:CAPSKIP_API_KEY = "YOUR_API_KEY" npx electron .
你发布出去的应用不能指望 127.0.0.1 上就有一个 CapSkip。要么每个用户在自己的 PC 上以 Local mode 运行 CapSkip,代码保持不变;要么你在自己掌控的一台 Windows 机器上以 Server mode 运行 CapSkip,它会监听你的网络或公网 IP,并由 CAPSKIP_HOST 指明那台机器。CAPSKIP_PORT 对 8080 以外的端口起同样的作用。 连接设置 里有这个开关,设置指南说明 Server mode 要求 CapSkip 以管理员身份运行,而使用固定地址能让应用始终指向同一个位置。
接下来是三条提醒。Server mode 启动时,CapSkip 会向所有地址开放它的端口,所以要把访问限制在你预期的机器上,就为其他机器添加一条 Windows Firewall 阻止规则,并开启 API Key Validation。SDK 构建的是一个没有 TLS 选项的 http 地址,所以一旦超出局域网或 VPN,密钥就会以明文传输。而且,你分发的应用里的密钥,任何运行它的人都能读到,所以要把它当作公开的。后两点是我对 SDK 源码的理解,不是测试结果。
常见错误
标为 mock 的行是我的模拟服务器通过真实 SDK 返回的内容;其余各行依据 CapSkip 文档。
| 处理程序的回复 | 原因 | 修复 |
|---|---|---|
| ApiException,附带 ERROR_KEY_DOES_NOT_EXIST(mock) | API Key Validation 已开启,而发送的密钥有误。没有 CAPSKIP_API_KEY 时,SDK 发送的是 capskip | 设置 CAPSKIP_API_KEY |
| NetworkException,附带 connect ECONNREFUSED(mock 端口) | 该主机和端口上没有任何程序在监听 | 启动 CapSkip,或修正 CAPSKIP_HOST 和端口 |
| TimeoutException,附带 timeout 60 exceeded(mock) | 在调用超时时间内没有拿到 token;回复在 63.0 秒时到达 | 打开 CapSkip Monitor,然后重试 |
| 消息中含有 ERROR_CAPTCHA_UNSOLVABLE 的 ApiException | 没有通过挑战。SDK 抛出的是原始回复文本;我没有检查真实的轮询错误体 | 用一个新任务重试 |
| ok true,但页面显示检查失败 | 表单已发出;站点拒绝了 token,常见原因是 User-Agent 或 token 存在时间不匹配 | 读取页面文本,并重新获取一个新的 token |
| error busy, window closed, no widget on the page | 这个处理程序自己的防护 | 等待后再点击一次(会打开一个新的页面窗口),或检查页面地址 |
常见问题
为什么不在渲染进程里调用 CapSkip?
沙盒化的渲染进程没有 require,所以 Node SDK 无法在那里加载,而且持有你密钥的渲染进程会把密钥暴露给它加载的每一个脚本。在主进程里,密钥只留在一个模块中。
CapSkip 这一侧能运行在服务器上,而不是用户的 PC 上吗?
可以,通过 Server mode,如上文所述。只有 CAPSKIP_HOST 需要改变,应用代码保持不变。
需要越过 CAPTCHA 的 Electron 应用,只需要找对进程:主进程调用 CapSkip,渲染进程显示结果,并在表单发出之前切换 User-Agent。如果你想要不带浏览器外壳的纯 Node.js 版本,请参阅 Node.js 版 Turnstile 指南。因为 CapSkip 是一款 验证码绕过 工具,运行在你自己的 PC 上,所以重试被拒绝的 token 不会产生额外费用。
