Nuxt Starter

Turnstile 表单测试

在独立留言表单中,试用 Cloudflare 人机验证与服务端核验。

演示页:/demos/turnstile。只做验证,不保存数据;注册和登录还没有接入。

测试模式

npm run dev:turnstile

打开 http://127.0.0.1:3000/demos/turnstile,可以切换“自动通过”“需要点击”“验证失败”三个场景。这里用的是官方测试钥匙,验证结果是预设的。

真实验证(本机即可,不需要域名)

  1. 在 Cloudflare 控制台的 Turnstile 里新建一个 Managed 组件,主机名填 localhost、127.0.0.1。

  2. 在 .env 里填写下面几项(用 Workers 预览时填 .dev.vars):

    NUXT_TURNSTILE_MODE=live
    NUXT_TURNSTILE_SITE_KEY=公开sitekey
    NUXT_TURNSTILE_SECRET_KEY=服务端secret
    NUXT_TURNSTILE_HOSTNAMES=localhost,127.0.0.1
    
  3. 运行 npm run dev,页面显示“真实验证”就说明配置生效了。

正式环境另建一个组件,主机名填正式域名,secret 用 Worker secret 设置。

接到自己的表单

以联系表单为例,action 起名 contact,前后端要写一致。

前端:放上组件,拿到 token 后才允许提交,提交时把 token 一起发给后端。

<script setup lang="ts">
const { data: config } = await useFetch('/api/demos/turnstile/config') // 拿公开 sitekey
const token = ref('')
const widget = useTemplateRef('widget')

async function submit() {
  try {
    await $fetch('/api/contact', { method: 'POST', body: { ...form, token: token.value } })
  } finally {
    token.value = ''        // token 只能用一次
    widget.value?.reset()   // 重新生成,方便重试
  }
}
</script>

<template>
  <ClientOnly>
    <TurnstileWidget v-if="config?.enabled" ref="widget" v-model="token" :site-key="config.siteKey" action="contact" />
  </ClientOnly>
  <UiButton :disabled="!token" @click="submit">发送</UiButton>
</template>

后端:在接口里先核验 token,通过了再走原来的业务逻辑。

const settings = turnstileSettings(useRuntimeConfig(event))   // server/turnstile/config.ts
if (!settings) throw createError({ statusCode: 503, statusMessage: 'TURNSTILE_NOT_CONFIGURED' })
const r = await $fetch<{ success: boolean, action?: string, hostname?: string }>(
  'https://challenges.cloudflare.com/turnstile/v0/siteverify',
  { method: 'POST', body: { secret: settings.secretKey, response: body.token } },
)
if (!r.success || (settings.mode === 'live'
  && (r.action !== 'contact' || !settings.hostnames.includes(r.hostname ?? ''))))
  throw createError({ statusCode: 403, statusMessage: 'TURNSTILE_REJECTED' })
// …原来的业务逻辑

只在前端加组件、后端不核验,等于没加防护。测试钥匙不会返回 action,hostname 固定是 example.com,所以只在 live 模式下核对这两项。

现在完整的核验写在 server/turnstile/submit.ts 里,和演示表单的字段校验写在一起。接第二个表单时,建议先把核验部分抽成单独的函数再复用。注册和登录走的是 Better Auth 的 /api/auth/[...all] 路由,没法直接在里面插入这段代码,需要另外处理。

用 AI 配置

安装 Cloudflare 官方技能,在安装器里选 turnstile-spin:

npx skills add https://github.com/cloudflare/skills

然后把下面这段发给 AI:

用 turnstile-spin 给 /demos/turnstile 配置本机真实验证。
主机名 localhost,127.0.0.1,沿用 NUXT_TURNSTILE_* 变量,
密钥只写入 .env 和 .dev.vars。不部署,不提交 Git。

如果已经建好组件,再补一句:“组件已创建,sitekey 是 xxx,不要新建。”

文件

文件 作用
app/components/TurnstileWidget.vue 渲染组件,拿到 token
app/pages/demos/turnstile.vue 表单页,提交邮箱、留言和 token
server/turnstile/submit.ts 调用 Siteverify,live 模式还会核对 hostname 和 action form-demo

检查

npm run turnstile:check:local                            # 本地替身,不联网
npm run turnstile:check:local -- http://127.0.0.1:3000   # 需先运行 dev:turnstile