Vue 聊天机器人：为 Vue 3 或 Nuxt 应用添加 AI 聊天机器人

您需要一个 Nexoply 账户和您的聊天机器人密钥。免费注册（免费版每月包含 50 次对话，无需信用卡），添加企业信息或从网站导入，然后在控制台中打开聊天机器人并复制安装代码。它看起来是这样的：

<script src="https://nexoply.com/widget.js" data-chatbot="YOUR-KEY" async></script>

data-chatbot 的值就是您的密钥。它是公开的，不是机密：它只用来告诉小组件属于哪家企业，因此可以放在客户端代码和您的代码仓库中。请严格保留属性名称以及包含 widget.js 的 src，因为小组件会从自身的 script 标签读取设置。

创建 src/components/Chatbot.vue。该组件自身不渲染任何内容：挂载时，它只向页面添加一次 Nexoply 脚本，由小组件绘制聊天按钮和聊天窗口。

<!-- src/components/Chatbot.vue -->
<script setup lang="ts">
import { onMounted } from "vue";

const props = defineProps<{ chatbotKey: string }>();

onMounted(() => {
  // 没有密钥，或脚本已在页面上：无需任何操作。
  if (!props.chatbotKey || document.querySelector("script[data-chatbot]")) return;
  const s = document.createElement("script");
  s.src = "https://nexoply.com/widget.js";
  s.async = true;
  s.dataset.chatbot = props.chatbotKey;
  document.body.appendChild(s);
});
</script>

<template><slot /></template>

在整个访问期间始终保持挂载的 App.vue 中渲染它一次。把密钥以 VITE_NEXOPLY_KEY=YOUR-KEY 的形式写入 .env：

<!-- src/App.vue -->
<script setup lang="ts">
import Chatbot from "./components/Chatbot.vue";

const nexoplyKey = import.meta.env.VITE_NEXOPLY_KEY;
</script>

<template>
  <!-- 您的布局和路由 -->
  <Chatbot :chatbot-key="nexoplyKey" />
</template>

在 JavaScript 项目中，请去掉 lang="ts"，并用 defineProps({ chatbotKey: String }) 代替类型参数。由于它是一个普通组件，您也可以用 v-if 渲染它，例如 v-if="hasConsent"，这样只有在访客接受您的同意横幅后才加载聊天。

不需要组件？最简单的安装方式是把该标签粘贴到项目根目录下的 index.html 中，紧挨在 </body> 之前。它以异步方式加载，绝不会阻塞渲染：

<body>
  <div id="app"></div>
  <script type="module" src="/src/main.ts"></script>
  <script src="https://nexoply.com/widget.js" data-chatbot="YOUR-KEY" async></script>
</body>

在 Nuxt 中不需要组件：在 nuxt.config.ts 中为整个网站添加脚本即可。tagPosition: "bodyClose" 会把它放在 </body> 之前：

export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: "https://nexoply.com/widget.js",
          async: true,
          "data-chatbot": "YOUR-KEY",
          tagPosition: "bodyClose",
        },
      ],
    },
  },
});

也可以在 app.vue 中用 useHead 添加。如果您想把密钥放在环境变量中，请在 nuxt.config.ts 中声明 runtimeConfig: { public: { nexoplyKey: "" } }并设置 NUXT_PUBLIC_NEXOPLY_KEY；否则直接在此处写入密钥即可：

<script setup lang="ts">
useHead({
  script: [
    {
      src: "https://nexoply.com/widget.js",
      async: true,
      "data-chatbot": useRuntimeConfig().public.nexoplyKey,
      tagPosition: "bodyClose",
    },
  ],
});
</script>

服务器端渲染没有问题：Nuxt 在 HTML 中渲染该标签，而小组件只在浏览器中运行。它不会触及您应用的标记，因此不会出现水合不匹配。

搜索 Vue 聊天机器人时，您会看到两类工具，它们解决的是不同的问题：

• 聊天机器人 UI 库为聊天界面本身提供 Vue 组件：消息列表、输入框、气泡，有时还有预设的对话步骤。界面背后的一切都需要您自己构建：固定脚本，或使用您自己的 API 密钥调用 AI 模型的后端，以及它作答所依据的内容、对话存储和防滥用措施。当聊天是您产品的一部分时，它很合适，例如一个处理您用户自有数据的助手。
• 托管式 AI 聊天机器人（例如 Nexoply）把界面、AI 和后端一起提供。它只根据您添加或导入的企业信息（服务和价格、常见问题、政策、营业时间）回答访客的问题，不知道时会如实说明。无需 AI 密钥，也无需服务器代码；对话、未解答问题和垃圾信息防护都在控制台中处理。它适合需要回答企业相关问题的面向客户的网站。

如果您希望完全掌控界面和模型，请从 UI 库入手。如果目标是回答访客的问题，又不想构建或运行后端，托管式小组件的工作量更小。请参阅 Nexoply 如何根据您的企业信息作答。

• 位于您的应用之外。它挂载在 document.body 上，位于 #app（或 Nuxt 的根节点）之外，因此重新渲染、布局变化和路由切换绝不会移除它。
• Vue Router 导航。访客在客户端于页面间跳转时，对话会继续进行；URL 变化时会再次检查页面规则（例如只在 /pricing 上显示侧边标签），无需额外代码。
• Shadow DOM。您的 CSS、Tailwind 类或 UI 库不会影响聊天窗口，聊天窗口的样式也不会影响您的应用。
• 轻量。它以异步方式加载，不设置 Cookie，只在 localStorage 中保存匿名访客 ID，在 sessionStorage 中保存当前对话。

想在首屏区域或价格表中放一个“有问题？问问我们”按钮？在点击处理函数中派发 nexoply:open-chat 事件即可：

<script setup lang="ts">
function openChat() {
  window.dispatchEvent(new Event("nexoply:open-chat"));
}
</script>

<template>
  <button type="button" @click="openChat">向我们提问</button>
</template>

如果要在页面加载后立即打开聊天，请在 script 标签中添加 data-open="true"（在 Nuxt 中为 "data-open": "true"）。

• 允许的网站。如果您在“聊天机器人”页面填写了仅允许在以下网站上使用，请把带端口的开发主机也加进去：Vite 为 localhost:5173，Nuxt 为 localhost:3000。或者在测试期间让该列表保持为空。
• Content-Security-Policy。如果您的应用发送 CSP 响应头，请在 script-src、connect-src 和 img-src 中允许 https://nexoply.com。
• 测试一下。运行开发服务器，打开应用，提一个真实的问题，然后确认这段对话出现在控制台的对话中。

如果按钮没有出现：

• 检查标签。在浏览器开发者工具中，查找带有 data-chatbot 属性且 src 包含 widget.js 的脚本。如果没有找到，密钥可能为空：请检查是否设置了 VITE_NEXOPLY_KEY 或 NUXT_PUBLIC_NEXOPLY_KEY，并在修改 .env 后重启开发服务器。
• 检查控制台和“网络”标签。CSP 错误表示尚未允许 nexoply.com；请求被拦截也可能来自广告拦截器，请在不带扩展的无痕窗口中试一试。
• 检查控制台设置。确认启用聊天机器人开关处于打开状态，并且如果您使用了允许列表，您的域名（或带端口的 localhost）已在其中。
• 是有意隐藏的吗？设置为“不显示按钮”的页面规则会在匹配的页面上隐藏它。

标签添加好之后，其余一切都在控制台中完成，更改大约一分钟内就会在网站上生效，无需重新部署。在聊天机器人 → 自定义中，您可以设置消息按钮的样式（图标或您自己的图片、文字标签、形状、大小、配色、位置），也可以改用屏幕边缘的侧边标签。您可以为手机设置不同的外观，并用页面规则在指定页面上更改或隐藏按钮（例如 /blog/*）。还可以让聊天窗口的样式与品牌相匹配，并在开始页面添加预约、致电或 WhatsApp 等按钮。

请查看 AI 助手如何了解您的企业和所有自定义选项，或比较各方案和对话限额。使用其他框架开发？请参阅 React 聊天机器人组件指南和如何用 next/script 为 Next.js 添加聊天机器人。