如何解决Vue项目中vue-turnstile集成的报错问题？

收到的警告 #

[Vue warn]: Missing ref owner context. ref cannot be used on hoisted vnodes. A vnode with ref must be created inside the render function. 
  at <VueTurnstile ref="reCaptchaTurnstile" site-key="324324rsdxdfw3r4fd" modelValue=""  ... > 

出现的错误 #

api.js?onload=cfTurnstileOnLoad&render=explicit:1 Uncaught (in promise) TurnstileError: [Cloudflare Turnstile] Invalid type for parameter "container", expected "string" or an implementation of "HTMLElement".

表单组件代码 #

<template>
  <div class="text-center contact-us-form">
    <h4 class="text-weight-bolder q-my-xs">GET A FREE QUOTE</h4>
    <div class="text-subtitle1 text-accent q-mb-xl">
      If you would like a quote or have any questions give us a call or send us
      an email using the contact form!
    </div>
    <q-form @submit="onSubmit" @reset="onReset">
      <div class="row q-col-gutter-md">
        <div class="col-6">
          <q-input
            filled
            v-model="firstName"
            label="First Name"
            hide-bottom-space
            lazy-rules="ondemand"
            :rules="[(val) => (val && val.length > 0) || 'First name required']"
          />
        </div>
        <div class="col-6">
          <q-input
            filled
            v-model="lastName"
            label="Last Name"
            hide-bottom-space
            lazy-rules="ondemand"
            :rules="[(val) => (val && val.length > 0) || 'Last name required']"
          />
        </div>
        <div class="col-12">
          <q-input
            filled
            v-model="phoneNumber"
            type="tel"
            mask="(###) ###-####"
            label="Phone Number"
            hide-bottom-space
            lazy-rules="ondemand"
            :rules="phoneNumberRules"
          />
        </div>
        <div class="col-12">
          <q-input
            filled
            v-model="emailAddress"
            type="email"
            label="Email"
            hide-bottom-space
            lazy-rules="ondemand"
            :rules="emailRules"
          />
        </div>
        <div class="col-12">
          <q-select
            filled
            v-model="typeOfService"
            :options="options"
            label="Type of Service"
            hide-bottom-space
            lazy-rules="ondemand"
            :rules="[
              (val) => (val && val.length > 0) || 'Type of service required',
            ]"
          />
        </div>
        <div class="col-12">
          <q-input
            v-model="message"
            filled
            clearable
            type="textarea"
            label="Subject"
            hide-bottom-space
            lazy-rules="ondemand"
            :rules="[(val) => (val && val.length > 0) || 'Message required']"
          />
        </div>
        <div class="col-12">
          <q-btn
            :loading="loading"
            color="primary"
            icon="send"
            label="Send"
            class="full-width q-pa-md"
            unelevated
            type="submit"
          >
            <template v-slot:loading>
              <q-spinner-gears class="q-ma-sm" /> Sending...
            </template>
          </q-btn>
        </div>
        <div class="col-12">
          <vue-turnstile
            ref="reCaptchaTurnstile"
            site-key="0x4AAAAAAAIGxTIQ6Z8JWGTo"
            v-model="token"
          />
        </div>
      </div>
    </q-form>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { useQuasar } from 'quasar';
import { api } from 'boot/axios';
import VueTurnstile from 'vue-turnstile';

//quasar variable
const $q = useQuasar();

//form inputs
const firstName = ref(null);
const lastName = ref(null);
const phoneNumber = ref(null);
const emailAddress = ref(null);
const typeOfService = ref(null);
const message = ref(null);
const token = ref('');
const reCaptchaTurnstile = ref(null); // we needed to define the ref for this so we could access reset()
const loading = ref(false);

// Drop down value for the services
const options = [
  'Chimney Repair',
  'Chimney Maintenance',
  'Chimney Inspection',
  'Other',
];

//form rules -- Added down here as reactive variables mainly due to complexity of their validation rules
const phoneNumberRules = ref([
  (v) => !!v || 'Phone number is required',
  (v) => v.length == 14 || 'Phone number must be valid',
]);
const emailRules = ref([
  (v) => !!v || 'E-mail is required',
  (v) =>
    /^\w+([.-]?\w+)*@\w+([.-]?\w+)*(\.\w{2,3})+$/.test(v) ||
    'E-mail must be valid',
]);

//methods
const onReset = () => {
  firstName.value = null;
  lastName.value = null;
  phoneNumber.value = null;
  emailAddress.value = null;
  typeOfService.value = null;
  message.value = null;
  token.value = '';
  reCaptchaTurnstile.value.reset();
};

const onSubmit = () => {
  //start widget spinner and turn of when complete
  loading.value = true;
  let jsonData = {
    FirstName: firstName.value,
    LastName: lastName.value,
    PhoneNumber: phoneNumber.value,
    EmailAddress: emailAddress.value,
    TypeOfService: typeOfService.value,
    Message: message.value,
    Token: token.value,
  };

  if (token.value != '') {
    api
      .post('/api/contactus', jsonData)
      .then((response) => {
        console.log(response);
        //reset the form
        onReset();

        loading.value = false;

        $q.notify({
          color: 'green-4',
          textColor: 'white',
          icon: 'cloud_done',
          message: 'Your message has been successfully sent!',
        });
      })
      .catch(() => {
        console.log('API request failed');
        loading.value = false;
      });
  }
};
</script>
<style lang="scss" scoped>
#cf-chl-widget-mpzku {
  width: 100% !important;
}

.contact-us-form {
  max-width: 450px;
  margin: auto;
}
</style>

已尝试的解决方法 #

• 卸载并重装vue-turnstile依赖，问题依旧
• 曾在其他项目中成功使用vue-turnstile，当前项目环境未知原因导致报错

1. 版本兼容性排查 #

vue-turnstile v2.x 要求 Vue 版本 >=3.2.34，如果当前项目 Vue 版本过低，会引发渲染逻辑冲突。

• 查看项目 Vue 版本：执行npm list vue或yarn list vue
• 处理方案：
  • 升级 Vue 到 3.2.34+
  • 或降级vue-turnstile到 v1.x（执行npm install vue-turnstile@1）

2. 修复Ref上下文缺失问题 #

Vue 的模板提升优化会导致组件 VNode 脱离当前渲染上下文，引发 ref 警告。可以通过以下方式规避：

方式一：用动态组件渲染 #

<component :is="VueTurnstile" ref="reCaptchaTurnstile" site-key="你的站点密钥" v-model="token" />

方式二：添加条件渲染（强制组件在当前上下文创建） #

<vue-turnstile v-if="true" ref="reCaptchaTurnstile" site-key="你的站点密钥" v-model="token" />

3. 显式指定容器元素 #

Cloudflare Turnstile 需要明确的容器元素，Quasar 的布局结构可能导致组件无法自动获取容器。手动指定容器：

<div id="turnstile-container" class="col-12">
  <vue-turnstile
    ref="reCaptchaTurnstile"
    site-key="你的站点密钥"
    v-model="token"
    container="turnstile-container"
  />
</div>

4. 全局注册组件替代局部导入 #

局部导入可能在 Quasar 环境下出现渲染异常，尝试全局注册：
在项目main.js中添加：

import { createApp } from 'vue'
import App from './App.vue'
import VueTurnstile from 'vue-turnstile'

const app = createApp(App)
app.use(VueTurnstile)
app.mount('#app')

然后移除组件内的import VueTurnstile from 'vue-turnstile'，直接在模板中使用<vue-turnstile>。

5. 调试Ref挂载时机 #

确保调用reset()时组件已完成挂载，添加onMounted钩子验证：

import { onMounted } from 'vue'

onMounted(() => {
  console.log('Turnstile ref:', reCaptchaTurnstile.value)
  // 如果输出为null，说明组件未正确渲染，优先检查版本兼容性
})

内容的提问来源于stack exchange，提问作者Qiuzman