遷移指南

從 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 片段就在文件裡。