Nuxt Turnstile

用于 Nuxt 3 的 Cloudflare Turnstile 集成

功能

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

安装

首先，按照这些步骤从 Cloudflare 获取免费的 sitekey 和 secret key。
安装 @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 设置为包含 secret key 的文件的路径。这将在构建时读取，并将覆盖您设置的任何其他显式 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 通过模板引用直接公开 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)
})

💻 开发

克隆此存储库
使用 corepack enable 启用 Corepack
使用 pnpm install 安装依赖项
使用 pnpm dev:prepare 存根模块
运行 pnpm dev 以在开发模式下启动游乐场

鸣谢

受 laravel-cloudflare-turnstile 启发

许可证

用心制作 ❤️

根据 MIT 许可证发布。