如何在Script Setup中使用vue3-tour？遇未定义及启动失败问题

问题背景 #

想用Vue3-Tour的Composition API写法，但官方文档只有Options API示例，参考已关闭的issue代码后遇到两个问题：

1. 初始代码里inject获取的tours是undefined
2. 解决tours未定义后，引导还是无法启动

问题1：tours为undefined的修复 #

初始代码的问题 #

你在main.ts里尝试用app.provide("tours", app.config.globalProperties.$tours)提供实例，但此时VueTour插件还没完成初始化，$tours还没挂载到全局属性上，所以inject拿不到值。

正确做法 #

不需要手动provide，直接通过组件实例访问$tours即可，注意两个关键点：

• 在<script setup>里用getCurrentInstance()获取实例后，要确保在组件挂载后访问proxy
• Vue3-Tour会自动把tour的name转为驼峰命名（比如home-tour会变成homeTour）

问题2：引导无法启动的排查与修复 #

从你编辑2的代码来看，tours未定义的问题已经解决，但引导没启动，大概率是以下原因：

原因1：目标元素#owner-btn还没渲染出来 #

#owner-btn在<router-view>的组件里，App组件的onMounted钩子执行时，路由组件可能还没渲染完，导致找不到目标元素。
解决方法：用nextTick等待DOM更新，或者把启动逻辑放到目标元素所在组件的onMounted里：

onMounted(async () => {
  await nextTick(); // 等路由组件渲染完成
  instance?.proxy?.$tours?.homeTour?.start();
});

原因2：遗漏了VueTour的样式文件 #

很多人会忘记引入样式，导致引导层无法正常显示，看起来像是没启动。
解决方法：在main.ts里加上样式导入：

import "vue3-tour/dist/vue3-tour.css";

原因3：目标元素选择器错误 #

检查#owner-btn是否真的存在，比如元素的id是否拼写正确，有没有被其他元素覆盖，或者选择器语法写错。

最终可运行代码示例 #

main.ts #

import { createApp } from "vue";
import router from "./router";
import VueTour from "vue3-tour";
import "vue3-tour/dist/vue3-tour.css"; // 必须引入样式
import App from "./App.vue";

const app = createApp(App).use(router).use(VueTour);
app.mount("#app");

App.vue #

<script setup lang="ts">
import NavigationDrawer from "@/components/NavigationDrawer.vue";
import { getCurrentInstance, onMounted, reactive, nextTick } from "vue";

const instance = getCurrentInstance();

const homeSteps = reactive([
  {
    target: "#owner-btn",
    content: "点击这个按钮创建所有者。",
  },
]);

onMounted(async () => {
  await nextTick();
  instance?.proxy?.$tours?.homeTour?.start();
});
</script>

<template>
  <v-app>
    <NavigationDrawer />
    <v-main>
      <v-container>
        <router-view />
      </v-container>
    </v-main>
    <v-tour name="homeTour" :steps="homeSteps"></v-tour>
  </v-app>
</template>

额外调试技巧 #

给v-tour加上debug属性，控制台会输出详细的调试信息，方便排查问题：

<v-tour name="homeTour" :steps="homeSteps" debug></v-tour>

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