For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh-tw/docs/web/captcha.md (or send Accept: text/markdown).

垃圾資訊防護

通過環境變數切換的 Turnstile 校驗，覆蓋公開表單與認證端點。

詢問本指南

初學者演練

先決條件：閱讀下面的兩個初學者指南，完成 Web 本地設定，並在編輯器的根目錄中開啟此 monorepo。網頁設定屬於apps/web/.env.local； Next.js不讀取根.env。預設fake模式下的/dashboard是無資料庫演示； /auth 需要遷移資料庫。

簡而言之：工作區是一個團隊的單獨使用者、資料和設定。伺服器是可信後端；讓提供商金鑰遠離瀏覽器和電話程式碼。遷移是建立或更新表的版本化資料庫更改。人工智慧模型是回答的引擎；型號目錄是伺服器上可用型號 ID 和價格的列表。提供商是一種外部服務，例如人工智慧、電子郵件或計費服務。權利是允許工作區使用某項功能的授權。 Webhook 是一個服務傳送到另一個服務的 URL 的訊息。

1. 為確切的本地/部署主機名建立 Turnstile 測試小部件。在apps/web/.env.local中，設定CAPTCHA_PROVIDER=turnstile和NEXT_PUBLIC_TURNSTILE_SITE_KEY；僅將 TURNSTILE_SECRET_KEY 放入伺服器秘密儲存中。

2. 重新啟動並提交測試聯絡表。

3. 期待挑戰和成功的有效令牌響應。如果每個請求都失敗，則比較主機名和金鑰對；永遠不要洩露秘密金鑰。

對於自定義程式碼，請從提供的 prompts/README.md 開始，然後複製最接近的提示：對於應用程式螢幕為 prompts/new-app-screen.md，對於公共頁面為 prompts/new-landing-page.md。對於伺服器、資料庫或提供商工作，請為您的編碼代理提供本指南的任務，並要求其讀取 AGENTS.md、.ai/PROJECT_CONTEXT.md 和匹配的 .ai/ 映象；檢查此處指定的確切原始檔；列出檔案並在編輯前進行檢查；保留工作區所有權和僅限伺服器的機密；並向您展示差異。告訴它您想要的行為、輸入和輸出欄位、允許的角色、預期的成功和錯誤以及測試帳戶、提供程式或裝置。使用樣本值；永遠不要貼上真正的秘密。

啟用兩個鍵

CAPTCHA_PROVIDER=off 是預設值。選擇 turnstile，在 Turnstile 應用程式中配置匹配的主機名並提供兩個金鑰。 NEXT_PUBLIC_TURNSTILE_SITE_KEY 為公開； TURNSTILE_SECRET_KEY僅供伺服器驗證者使用。

CAPTCHA_PROVIDER=turnstile
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your-site-key
# TURNSTILE_SECRET_KEY belongs in the server secret store.

保護受保護的表面

該門涵蓋聯絡/新聞通訊表格以及 Better Auth 登入、註冊、OTP 和密碼重置憑證端點。它補充了驗證/速率限制；它不能替代會話或工作區授權。

驗證拒絕和恢復

測試有效令牌、丟失/過期/無效令牌、驗證器失敗以及客戶端小部件重置後的重試。保留可操作的人工檢查副本和鍵盤訪問；在切換提供商之前檢查所選身份驗證引擎的覆蓋範圍。

安裝與配置

CAPTCHA_PROVIDER 選擇驗證器：off（預設，本地開發無需憑據）或 turnstile。啟用 turnstile 需要服務端配置 TURNSTILE_SECRET_KEY，客戶端元件使用 NEXT_PUBLIC_TURNSTILE_SITE_KEY——任一缺失時 config schema 會讓啟動直接失敗。

apps/web/src/captcha.ts 組合出一個程式級共享驗證器，將 token 以十秒超時傳送到 Cloudflare 的 siteverify 端點，並採用失敗即拒絕策略——無法驗證的 token 永遠不算人類證明。

CAPTCHA_PROVIDER=turnstile
TURNSTILE_SECRET_KEY=…           # server-only
NEXT_PUBLIC_TURNSTILE_SITE_KEY=…

Guarded: sign-in/up, OTP send, reset,
contact + newsletter forms

實現流程

CaptchaWidget（src/captcha-widget.tsx）渲染元件並把 cf-turnstile-response 欄位注入父表單，認證客戶端呼叫則通過 x-captcha-response 頭攜帶 token。聯絡與訂閱動作在寫入前完成校驗——校驗失敗會返回 status=captcha，而不會建立線索。

當 provider 開啟時，packages/auth 掛載 better-auth 的 captcha 外掛；CAPTCHA_ENDPOINTS 覆蓋憑據輸入與簽發 token 的路由——登入、註冊、OTP 傳送、密碼重置。check-verification-otp 這類消費型端點被有意排除在外：那裡 OTP 或 token 本身就是證明。

驗證與排障

對每個受保護表單分別提交缺失 token 與畸形 token——兩者都必須失敗即拒絕。驗證 siteverify 不可達時是拒絕而不是放行，provider=off 時本地開發保持開放，且 secret 永遠不會出現在客戶端打包產物或日誌中。