Nuxt Turnstile

Cloudflare Turnstile 与 Nuxt 3 的集成

特性

💪 智能验证，最少用户交互
🕵️‍♀️ 注重隐私的方法
✨ 用于您的 Nitro 端点的服务器验证助手
⚡️ 轻量级 - 脚本仅在需要时加载

安装

首先，按照这些步骤从 Cloudflare 获取免费的站点密钥和密钥。
安装 @nuxt/scripts 作为依赖项 - 如果您有兴趣，请参阅文档以获取更多信息。

安装并将 @nuxtjs/turnstile 添加到您的 nuxt.config。

npx nuxi@latest module add turnstile

export default defineNuxtConfig({
  modules: ['@nuxtjs/turnstile'],

  turnstile: {
    siteKey: '<your-site-key>',
  },

  runtimeConfig: {
    turnstile: {
      // This can be overridden at runtime via the NUXT_TURNSTILE_SECRET_KEY
      // environment variable.
      secretKey: '',
    },
  },
})

或者，您可以将 turnstile.secretKeyPath 设置为包含密钥的文件路径。这将在构建时读取，并将覆盖您已设置的任何其他显式 secretKey。

提示：在运行时，您可以使用 NUXT_TURNSTILE_SECRET_KEY 和 NUXT_PUBLIC_TURNSTILE_SITE_KEY 环境变量覆盖站点密钥和密钥。

用法

要使用 Turnstile，您可能需要

在您的应用程序中使用 <NuxtTurnstile> 组件（例如，构建联系表单）
在您的服务器上验证令牌，当您处理 API 请求或表单提交时（例如，在发送电子邮件之前）

客户端

要使用 Turnstile，请在任何需要它的组件中添加自动导入的 Vue 组件

<template>
  <div>
    <form @submit.prevent="onSubmit">
      <NuxtTurnstile v-model="token" />
      <input type="submit" />
    </form>
  </div>
</template>

<NuxtTurnstile> 可以通过 options 参数接收多个选项。查看所有选项。默认情况下，它在 <div> 包装器中渲染 Turnstile <iframe>，但您可以通过设置 element 属性来配置它。

在页面中时，它将自动加载 Turnstile 脚本并验证您的用户。每次验证持续 300 秒，@nuxtjs/turnstile 将在 250 秒后自动重新验证此令牌。

您可以通过在组件上设置 v-model 来访问验证令牌。然后，将令牌与您的表单响应一起发送，无论是显式地还是自动地（Cloudflare 会将一个名为 cf-turnstile-response 的隐藏表单元素添加到您的表单中）。要在服务器端验证令牌，您可以使用 Nitro 服务器路由中自动导入的 verifyTurnstileToken 实用程序。

turnstile 令牌在通过 verifyTurnstileToken 与 CloudFlare 处理后不再有效。如果您将 @nuxtjs/turnstile 与可能需要多次验证的组件（例如提交表单）一起使用，则需要为每次提交重新生成令牌。要手动重新生成令牌，@nuxtjs/turnstile 通过模板 ref 直接公开 reset 函数。

示例:

<template>
  <NuxtTurnstile ref="turnstile" />
  <button @click="turnstile.reset()">Reset token in template</button>
  <button @click="reset()">Reset token from handler</button>
</template>

<script setup>
  // you can call this template ref anything
  const turnstile = ref()

  function reset() {
    turnstile.value?.reset()
  }
</script>

服务器

您可以使用生成的验证端点，或使用导入的辅助方法

使用端点的示例:

首先开启端点的生成

export default defineNuxtConfig({
  // ...
  turnstile: {
    siteKey: '<your-site-key>',
    addValidateEndpoint: true
  },
})

您现在可以从客户端调用 /_turnstile/validate 上的端点来验证令牌。

使用自定义端点和辅助方法的示例:

// server/api/validateTurnstile.ts

export default defineEventHandler(async (event) => {
  const { token } = await readBody(event)

  if (!token) {
    throw createError({
      statusCode: 422,
      statusMessage: 'Token not provided.',
    })
  }

  return await verifyTurnstileToken(token)
})