turnstile
@nuxtjs/turnstile

Cloudflare 提供的注重隱私的 CAPTCHA 替代方案

Nuxt Turnstile

npm versionnpm downloadsGithub ActionsCodecov

Cloudflare TurnstileNuxt 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_KEYNUXT_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 引數接受許多選項。檢視所有選項。預設情況下,它將 Turnstile <iframe> 渲染在 <div> 包裝器內,但您可以透過設定 element prop 來配置此項。

當在頁面中時,它將自動載入 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

鳴謝

許可證

用 ❤️ 製作

MIT 許可證下發布。