Nuxt Turnstile

Cloudflare Turnstile 整合適用於 Nuxt 3

功能

💪 透過最少的用戶互動進行智慧驗證
🕵️‍♀️ 以隱私為中心的方法
✨ 您的 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 環境變數來覆寫 site 和 secret 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)
})