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 实用程序。

通过 verifyTurnstileToken 使用 Cloudflare 处理后，turnstile 令牌将不再有效。如果您正在使用 @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)
})