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 實用程式。

turnstile 權杖在透過 verifyTurnstileToken 與 CloudFlare 處理後即失效。如果您將 @nuxtjs/turnstile 與可能需要多次驗證的元件（例如提交表單）一起使用，您將需要為每次提交重新產生權杖。若要手動重新產生權杖，@nuxtjs/turnstile 會透過 template 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)
})