Turnstile 表单测试
在独立留言表单中,试用 Cloudflare 人机验证与服务端核验。
演示页:/demos/turnstile。只做验证,不保存数据;注册和登录还没有接入。
测试模式
npm run dev:turnstile
打开 http://127.0.0.1:3000/demos/turnstile,可以切换“自动通过”“需要点击”“验证失败”三个场景。这里用的是官方测试钥匙,验证结果是预设的。
真实验证(本机即可,不需要域名)
在 Cloudflare 控制台的 Turnstile 里新建一个 Managed 组件,主机名填
localhost、127.0.0.1。在
.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运行
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