Nuxt Turnstile

Cloudflare Turnstile 集成到 Nuxt 3

• ✨  更新日志
• ▶️  在线演练场

功能

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

安装

1. 首先，按照这些步骤从 Cloudflare 获取免费的站点密钥和秘密密钥。
2. 安装 @nuxt/scripts 作为依赖项 - 如果您有兴趣，请参阅文档以获取更多信息。
3. 安装 @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 通过模板引用直接暴露 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 以在开发模式下启动 playground

鸣谢

• 灵感来自 laravel-cloudflare-turnstile

许可证

用 ❤️ 制作

在 MIT 许可证下发布。