React 聊天机器人：为您的 React 应用添加 AI 聊天机器人（Vite、CRA、SPA）

在改动代码之前，您需要准备两样东西：

• 一个 Nexoply 账户和您的聊天机器人密钥。免费注册（免费版每月包含 50 次对话，无需信用卡），然后在控制台中打开聊天机器人。那里的安装代码已经包含您的密钥。该密钥是公开的：它不是机密，也无法访问账户，因此可以放在客户端代码中。
• AI 助手作答所依据的企业信息：服务和价格、常见问题、政策、营业时间和服务范围。最快的方法是输入网站地址，让 Nexoply 导入公开页面，包括用 JavaScript 构建的页面，因此 React 网站同样适用。所有内容都需经批准后才会添加。

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

// src/components/Chatbot.tsx
import { useEffect } from "react";

type ChatbotProps = { chatbotKey: string };

export function Chatbot({ chatbotKey }: ChatbotProps) {
  useEffect(() => {
    // 没有密钥，或脚本已在页面上：无需任何操作。
    if (!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 = chatbotKey;
    document.body.appendChild(s);
  }, [chatbotKey]);

  return null;
}

在整个访问期间始终保持挂载的组件（通常是 App）中渲染它一次。在 Vite 中，把 VITE_NEXOPLY_KEY=YOUR-KEY 写入 .env 文件：

// src/App.tsx
import { Chatbot } from "./components/Chatbot";

export default function App() {
  return (
    <>
      {/* 您的布局和路由 */}
      <Chatbot chatbotKey={import.meta.env.VITE_NEXOPLY_KEY} />
    </>
  );
}

该组件可直接用于基于 Vite 或 Create React App 的 TypeScript 项目。如果使用纯 JavaScript，请将文件命名为 Chatbot.jsx，并删除 ChatbotProps 类型。Create React App 没有 import.meta.env：请改为传入 process.env.REACT_APP_NEXOPLY_KEY。由于它是一个普通组件，您也可以按条件渲染它，例如 {hasConsent && <Chatbot chatbotKey={key} />}，这样只有在访客接受您的 Cookie 横幅后才加载聊天。

• 为什么没有清理函数。小组件加载后没有用于移除它的 API，而且它位于您的 React 树之外，因此卸载组件时无需撤销任何操作。
• 为什么 StrictMode 没有问题。在开发环境中，React StrictMode 会运行两次副作用。querySelector 检查会跳过第二次运行；即使脚本被添加了两次，小组件对每个聊天机器人密钥也只挂载一次。出于同样的原因，热重载也是安全的。
• 保留该属性。小组件从自身的 script 标签读取设置，因此该标签必须保留 data-chatbot 属性，并且 src 中包含 widget.js。设置 s.dataset.chatbot 就会创建这个属性。

如果您不需要通过代码控制加载，可以跳过组件。每个 React SPA 都有一个 HTML 外壳：在 Vite 中是项目根目录下的 index.html；在 Create React App 中是 public/index.html。将代码粘贴到结束标签 </body> 之前：

<body>
  <div id="root"></div>
  <script type="module" src="/src/main.tsx"></script>

  <!-- Nexoply AI 聊天机器人 -->
  <script src="https://nexoply.com/widget.js" data-chatbot="YOUR-KEY" async></script>
</body>

将 YOUR-KEY 替换为“聊天机器人”页面上的密钥。脚本以异步方式加载，因此绝不会阻塞您的应用渲染。如果希望页面加载时就打开聊天窗口，请在标签中添加 data-open="true"。安装到此完成：重新构建、部署，按钮就会显示在每个路由上。

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

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

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

• 不进入您的 React 树。小组件挂载在 document.body 上，位于 #root 元素之外，因此重新渲染和路由切换绝不会移除它或改变它的样式。
• 双向隔离的 Shadow DOM。您的 CSS（Tailwind、CSS Modules、全局重置样式）不会影响聊天窗口，聊天窗口的 CSS 也不会影响您的应用。
• 路由切换无需额外处理。使用 React Router 或任何基于 history 的路由时，访客在页面间跳转仍会保留对话；URL 变化时会重新检查页面规则（例如只在 /pricing 上显示侧边标签）。无需额外代码。
• 不使用 Cookie。它在 localStorage 中保存匿名访客 ID，在 sessionStorage 中保存当前对话。

想在首屏区域或价格页面上放一个“与我们聊天”按钮？在 window 上派发 nexoply:open-chat 事件即可：

export function ChatButton() {
  return (
    <button onClick={() => window.dispatchEvent(new Event("nexoply:open-chat"))}>
      与我们聊天
    </button>
  );
}

无需任何 import：小组件会在 window 上监听这个事件。如果您只想显示自己的按钮，请在控制台中通过页面规则把消息按钮设置为“不显示按钮”。

部署之前，请检查以下三项设置：

• 允许的网站。如果您填写了仅允许在以下网站上使用（控制台 → 聊天机器人），请添加带端口的开发主机，例如 Vite 的 localhost:5173 或 Create React App 的 localhost:3000；也可以在测试期间让该列表保持为空。
• Content-Security-Policy。如果您的应用发送 CSP 响应头或 meta 标签，请在 script-src、connect-src 和 img-src 中允许 https://nexoply.com。
• 完整检查一遍。运行应用，点击聊天按钮，提一个真实的问题，然后在控制台的对话中查找它。

如果按钮仍然没有出现：

• 密钥为空。没有密钥时，组件不会加载任何内容。请打印 import.meta.env.VITE_NEXOPLY_KEY：Vite 只公开以 VITE_ 开头的变量，并且修改 .env 后需要重启开发服务器。
• 请求被拦截。在浏览器控制台和“网络”标签中查看是否有 CSP 错误，或 widget.js 是否被拦截。
• 聊天机器人已关闭。请确认启用聊天机器人开关处于打开状态。
• 广告拦截器。在极少数情况下，浏览器扩展会拦截聊天小组件。请在不带扩展的无痕窗口中试一试。

脚本添加好之后，您就不必再改动代码：在控制台中所做的更改大约一分钟内就会生效。在聊天机器人 → 自定义中，您可以设置消息按钮的样式（图标或您自己的图片或 SVG、文字标签、形状、大小、配色、位置），也可以改用屏幕边缘的侧边标签。您可以为手机设置不同的外观，并用页面规则在指定路由上更改外观（例如 /pricing 或 /services/*）。聊天窗口会采用您的字体、配色和标志，开始页面还可以提供预约、致电或 WhatsApp 等按钮。

使用其他框架？请参阅如何用 next/script 为 Next.js 添加聊天机器人或 Vue 和 Nuxt 聊天机器人指南；如果是 WordPress 营销网站，请参阅 WordPress 指南。如需全面了解，请阅读 AI 助手如何了解您的企业，或比较各方案和对话限额。