迁移指南

从 reCAPTCHA 迁移到 CaptchaLa

10 分钟内即插即用完成替换。表单照旧,只换验证服务商。支持纯 HTML、WordPress、Flarum 以及任何后端。

GreCAPTCHACurrent setup~10 minCaptchaLaDrop-in target

代码改动长这样

Before — reCAPTCHA v2
<div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY"></div>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
After — CaptchaLa
<button id="login-btn">Sign in</button>
<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>
<script>
  loadCaptchala(() => Captchala.init({ appKey: 'YOUR_APP_KEY', action: 'login' })
    .onSuccess(res => onToken(res.token))
    .bindTo('#login-btn'));
</script>
Before — reCAPTCHA server verify (Node)
const res = await fetch('https://www.google.com/recaptcha/api/siteverify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    secret: process.env.RECAPTCHA_SECRET,
    response: req.body['g-recaptcha-response'],
  }),
})
const data = await res.json()
if (!data.success) return res.status(400).json({ error: 'bot' })
After — CaptchaLa server verify (Node)
const res = await fetch('https://apiv1.captcha.la/v1/validate', {
  method: 'POST',
  headers: {
    'X-App-Key': process.env.CAPTCHALA_APP_KEY,
    'X-App-Secret': process.env.CAPTCHALA_APP_SECRET,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ pass_token: req.body['captchala-token'] }),
})
const { data } = await res.json()
if (!data || !data.valid) return res.status(400).json({ error: 'bot' })

迁移步骤

  1. 1

    注册并取得你的 App Key + Secret

    创建免费 CaptchaLa 账号、添加一个站点,拷贝 App Key(公开)与 App Secret(服务器端)。免绑卡。

  2. 2

    替换表单中的组件标签

    把 reCAPTCHA 的 div 与 script src 换成 CaptchaLa 对应的版本。标签 class 从 g-recaptcha 改为 captchala,data-sitekey 改为 data-app-key,script URL 指向我们的 CDN。

  3. 3

    更新表单提交的字段名称

    reCAPTCHA 会注入一个名为 g-recaptcha-response 的隐藏字段,CaptchaLa 使用 captchala-token。如果你的表单处理程序是依名称读取该字段,改一下常数即可;否则隐藏输入会自动带过去。

  4. 4

    更新服务器端验证

    将验证请求指向 apiv1.captcha.la/v1/validate,在标头带上 App 凭证(X-App-Key / X-App-Secret),并在 JSON body 中传入 pass_token。回应结构回传的 valid 旗标(data.valid)与 reCAPTCHA 相同,因此既有的分支逻辑不必改。

  5. 5

    逐步上线

    多数团队会先在一个表单(通常是流量最低的,例如电子报订阅或联系表单)上线,观察几小时的转化与验证率,再扩大范围。没有最低消费、没有合约,灰度上线完全免费。

常见问题

我需要一次把所有表单都迁移完吗?

不需要。两套系统可在同一站点共存——它们不共享状态或 cookie。一次迁移一个表单即可。

reCAPTCHA Enterprise 的风险分数呢?分数会转移吗?

分数不会转移(那是厂商内部数据),但 CaptchaLa 会在验证回应中回传自己的风险分数。数值范围与决策逻辑都有文档说明;团队通常一小时内就能把既有的分数门槛(例如 0.5)对应到我们的标准。

我的 Google 站点验证或其他 Google 集成会坏掉吗?

不会。reCAPTCHA 与 Search Console/站点验证/Analytics 是分开的。移除 reCAPTCHA 标签不会影响任何其他 Google 服务。

对于嵌入大量 reCAPTCHA 标签的站点,有没有迁移脚本?

我们不提供(寻找替换每个 repo 只是一条 regex,而每个程序库的模板各不相同)。多数团队使用的 10 行 shell 片段就在文档里。