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/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 永远不会出现在客户端打包产物或日志中。