[{"data":1,"prerenderedAt":24},["ShallowReactive",2],{"doc-turnstile":3},{"slug":4,"title":5,"description":6,"lastmod":7,"toc":8,"html":23},"turnstile","Turnstile 表单测试","在独立留言表单中，试用 Cloudflare 人机验证与服务端核验。","2026-11-18",[9,11,14,16,19,21],{"id":10,"text":10},"测试模式",{"id":12,"text":13},"真实验证-本机即可-不需要域名","真实验证（本机即可，不需要域名）",{"id":15,"text":15},"接到自己的表单",{"id":17,"text":18},"用-ai-配置","用 AI 配置",{"id":20,"text":20},"文件",{"id":22,"text":22},"检查","\u003Cp>演示页：\u003Ca href=\"\u002Fdemos\u002Fturnstile\">\u002Fdemos\u002Fturnstile\u003C\u002Fa>。只做验证，不保存数据；注册和登录还没有接入。\u003C\u002Fp>\n\u003Ch2 id=\"测试模式\">测试模式\u003C\u002Fh2>\n\u003Cpre>\u003Ccode class=\"language-bash\">npm run dev:turnstile\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>打开 \u003Ccode>http:\u002F\u002F127.0.0.1:3000\u002Fdemos\u002Fturnstile\u003C\u002Fcode>，可以切换“自动通过”“需要点击”“验证失败”三个场景。这里用的是官方测试钥匙，验证结果是预设的。\u003C\u002Fp>\n\u003Ch2 id=\"真实验证-本机即可-不需要域名\">真实验证（本机即可，不需要域名）\u003C\u002Fh2>\n\u003Col>\n\u003Cli>\u003Cp>在 Cloudflare 控制台的 Turnstile 里新建一个 Managed 组件，主机名填 \u003Ccode>localhost\u003C\u002Fcode>、\u003Ccode>127.0.0.1\u003C\u002Fcode>。\u003C\u002Fp>\n\u003C\u002Fli>\n\u003Cli>\u003Cp>在 \u003Ccode>.env\u003C\u002Fcode> 里填写下面几项（用 Workers 预览时填 \u003Ccode>.dev.vars\u003C\u002Fcode>）：\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-dotenv\">NUXT_TURNSTILE_MODE=live\nNUXT_TURNSTILE_SITE_KEY=公开sitekey\nNUXT_TURNSTILE_SECRET_KEY=服务端secret\nNUXT_TURNSTILE_HOSTNAMES=localhost,127.0.0.1\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003C\u002Fli>\n\u003Cli>\u003Cp>运行 \u003Ccode>npm run dev\u003C\u002Fcode>，页面显示“真实验证”就说明配置生效了。\u003C\u002Fp>\n\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Cp>正式环境另建一个组件，主机名填正式域名，secret 用 Worker secret 设置。\u003C\u002Fp>\n\u003Ch2 id=\"接到自己的表单\">接到自己的表单\u003C\u002Fh2>\n\u003Cp>以联系表单为例，action 起名 \u003Ccode>contact\u003C\u002Fcode>，前后端要写一致。\u003C\u002Fp>\n\u003Cp>\u003Cstrong>前端\u003C\u002Fstrong>：放上组件，拿到 token 后才允许提交，提交时把 token 一起发给后端。\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-vue\">&lt;script setup lang=&quot;ts&quot;&gt;\nconst { data: config } = await useFetch(&#39;\u002Fapi\u002Fdemos\u002Fturnstile\u002Fconfig&#39;) \u002F\u002F 拿公开 sitekey\nconst token = ref(&#39;&#39;)\nconst widget = useTemplateRef(&#39;widget&#39;)\n\nasync function submit() {\n  try {\n    await $fetch(&#39;\u002Fapi\u002Fcontact&#39;, { method: &#39;POST&#39;, body: { ...form, token: token.value } })\n  } finally {\n    token.value = &#39;&#39;        \u002F\u002F token 只能用一次\n    widget.value?.reset()   \u002F\u002F 重新生成，方便重试\n  }\n}\n&lt;\u002Fscript&gt;\n\n&lt;template&gt;\n  &lt;ClientOnly&gt;\n    &lt;TurnstileWidget v-if=&quot;config?.enabled&quot; ref=&quot;widget&quot; v-model=&quot;token&quot; :site-key=&quot;config.siteKey&quot; action=&quot;contact&quot; \u002F&gt;\n  &lt;\u002FClientOnly&gt;\n  &lt;UiButton :disabled=&quot;!token&quot; @click=&quot;submit&quot;&gt;发送&lt;\u002FUiButton&gt;\n&lt;\u002Ftemplate&gt;\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>\u003Cstrong>后端\u003C\u002Fstrong>：在接口里先核验 token，通过了再走原来的业务逻辑。\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-ts\">const settings = turnstileSettings(useRuntimeConfig(event))   \u002F\u002F server\u002Fturnstile\u002Fconfig.ts\nif (!settings) throw createError({ statusCode: 503, statusMessage: &#39;TURNSTILE_NOT_CONFIGURED&#39; })\nconst r = await $fetch&lt;{ success: boolean, action?: string, hostname?: string }&gt;(\n  &#39;https:\u002F\u002Fchallenges.cloudflare.com\u002Fturnstile\u002Fv0\u002Fsiteverify&#39;,\n  { method: &#39;POST&#39;, body: { secret: settings.secretKey, response: body.token } },\n)\nif (!r.success || (settings.mode === &#39;live&#39;\n  &amp;&amp; (r.action !== &#39;contact&#39; || !settings.hostnames.includes(r.hostname ?? &#39;&#39;))))\n  throw createError({ statusCode: 403, statusMessage: &#39;TURNSTILE_REJECTED&#39; })\n\u002F\u002F …原来的业务逻辑\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>只在前端加组件、后端不核验，等于没加防护。测试钥匙不会返回 action，hostname 固定是 \u003Ccode>example.com\u003C\u002Fcode>，所以只在 live 模式下核对这两项。\u003C\u002Fp>\n\u003Cp>现在完整的核验写在 \u003Ccode>server\u002Fturnstile\u002Fsubmit.ts\u003C\u002Fcode> 里，和演示表单的字段校验写在一起。接第二个表单时，建议先把核验部分抽成单独的函数再复用。注册和登录走的是 Better Auth 的 \u003Ccode>\u002Fapi\u002Fauth\u002F[...all]\u003C\u002Fcode> 路由，没法直接在里面插入这段代码，需要另外处理。\u003C\u002Fp>\n\u003Ch2 id=\"用-ai-配置\">用 AI 配置\u003C\u002Fh2>\n\u003Cp>安装 Cloudflare 官方技能，在安装器里选 \u003Ccode>turnstile-spin\u003C\u002Fcode>：\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-bash\">npx skills add https:\u002F\u002Fgithub.com\u002Fcloudflare\u002Fskills\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>然后把下面这段发给 AI：\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-text\">用 turnstile-spin 给 \u002Fdemos\u002Fturnstile 配置本机真实验证。\n主机名 localhost,127.0.0.1，沿用 NUXT_TURNSTILE_* 变量，\n密钥只写入 .env 和 .dev.vars。不部署，不提交 Git。\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>如果已经建好组件，再补一句：“组件已创建，sitekey 是 xxx，不要新建。”\u003C\u002Fp>\n\u003Ch2 id=\"文件\">文件\u003C\u002Fh2>\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>文件\u003C\u002Fth>\n\u003Cth>作用\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>\u003Ccode>app\u002Fcomponents\u002FTurnstileWidget.vue\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>渲染组件，拿到 token\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>app\u002Fpages\u002Fdemos\u002Fturnstile.vue\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>表单页，提交邮箱、留言和 token\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>server\u002Fturnstile\u002Fsubmit.ts\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>调用 Siteverify，live 模式还会核对 hostname 和 action \u003Ccode>form-demo\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\u003C\u002Ftable>\n\u003Ch2 id=\"检查\">检查\u003C\u002Fh2>\n\u003Cpre>\u003Ccode class=\"language-bash\">npm run turnstile:check:local                            # 本地替身，不联网\nnpm run turnstile:check:local -- http:\u002F\u002F127.0.0.1:3000   # 需先运行 dev:turnstile\n\u003C\u002Fcode>\u003C\u002Fpre>\n",1795050222295]