Next.js 聊天机器人：用 next/script 添加 AI 聊天机器人（App Router 和 Pages Router）

• 一个 Nexoply 账户。免费注册：免费版每月包含 50 次对话，无需信用卡。
• 在 Nexoply 中添加企业信息：服务和价格、常见问题、政策、营业时间和服务范围。最快的方法是输入网站地址，让 Nexoply 导入公开页面（包括用 JavaScript 渲染的页面）；您审核建议内容，所有内容都需经您批准后才会添加。
• 您的聊天机器人密钥。在控制台中打开聊天机器人（如果还没有创建，请点击创建聊天机器人）。那里的安装代码在 data-chatbot 属性中包含该密钥。

如果是普通 HTML 网站，只需把安装代码粘贴到 </body> 之前：

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

在 Next.js 中您不会直接编辑 HTML，因此改用内置的 next/script 组件添加同样的脚本。该密钥是公开的：它只用来告诉小组件属于哪家企业。

根布局包裹着每个页面，因此在这里添加脚本，聊天就会出现在整个网站上。从 next/script 导入 Script，并把它放在 <body> 内、{children} 之后：

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        {/* Nexoply 聊天小组件：水合完成后在浏览器中加载 */}
        <Script
          src="https://nexoply.com/widget.js"
          data-chatbot={process.env.NEXT_PUBLIC_NEXOPLY_KEY}
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

然后把密钥放进环境变量。NEXT_PUBLIC_ 前缀会让 Next.js 将它打包进浏览器端代码，这里没有问题，因为密钥并不是机密：

# .env.local（不提交到 git）
NEXT_PUBLIC_NEXOPLY_KEY=YOUR-KEY

在 Pages Router 中，pages/_app.tsx 包裹着每个页面，因此同样的 <Script> 放在这里，与 <Component {...pageProps} /> 并列。使用同一个 .env.local 变量：

// pages/_app.tsx
import type { AppProps } from "next/app";
import Script from "next/script";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://nexoply.com/widget.js"
        data-chatbot={process.env.NEXT_PUBLIC_NEXOPLY_KEY}
        strategy="afterInteractive"
      />
    </>
  );
}

如果您的项目同时使用两种路由，请在 app/layout.tsx 和 pages/_app.tsx 中都添加脚本。加载两次不会有问题：小组件对每个聊天机器人密钥只挂载一次。

更喜欢像 React 聊天机器人组件指南那样使用 <Chatbot /> 组件？把 Script 移到单独的文件中即可。只要不传入 onLoad 等事件处理函数，next/script 就能在服务器组件中使用，因此这个文件不需要 "use client"：

// components/Chatbot.tsx
import Script from "next/script";

export function Chatbot() {
  return (
    <Script
      src="https://nexoply.com/widget.js"
      data-chatbot={process.env.NEXT_PUBLIC_NEXOPLY_KEY}
      strategy="afterInteractive"
    />
  );
}

然后在 app/layout.tsx 的 <body> 内、{children} 之后渲染 <Chatbot />，或在 pages/_app.tsx 中与 <Component {...pageProps} /> 并列渲染。请在布局中渲染它，而不是在单个页面中，这样它才会在每个路由上加载。

strategy="afterInteractive" 会在页面可交互后立即加载小组件，因此聊天按钮很快就会出现。strategy="lazyOnload" 会等到浏览器空闲、其他内容都加载完毕后再加载；如果您希望首次加载尽可能轻量，也不介意按钮稍晚出现，可以选择它。两种方式都会让脚本远离关键渲染路径。详情请参阅 next/script 文档。

• 客户端导航。访客通过 <Link> 或路由器在页面间跳转时，小组件会保持对话打开，并在 URL 变化时重新检查您的页面规则，无需额外代码。
• SSR 和水合安全。它只在浏览器中运行，挂载在 document.body 上，位于 React 水合的标记之外，因此绝不会导致水合不匹配。
• Shadow DOM。您的 Tailwind 或全局 CSS 不会影响聊天窗口，聊天窗口的样式也不会影响您的应用。重新渲染绝不会移除它。
• StrictMode 和 Fast Refresh。开发环境中副作用运行两次或热重载，都不会产生第二个聊天：它对每个密钥只挂载一次。
• 存储。它不设置 Cookie；它用 localStorage 保存匿名访客 ID，用 sessionStorage 保存当前对话。

用 Next.js 自己构建聊天机器人并不难，有时这也是正确的选择。两种做法适合不同的需求：

• 自己构建：使用聊天 UI 库或您自己的组件，再加上一个用您自己的 API 密钥调用 AI 模型的 route handler 或 API 路由。它作答所依据的内容、对话存储和防滥用措施也都由您负责。当聊天是您产品的一部分时，它很合适，例如一个处理您用户自有数据的助手。
• 托管式 AI 聊天机器人（例如 Nexoply）把界面、AI 和后端一起提供。它只根据您添加或导入的企业信息（服务和价格、常见问题、政策、营业时间）回答访客的问题，不知道时会如实说明。无需 AI 密钥，您的服务器上也不运行任何东西；对话、未解答问题和垃圾信息防护都在控制台中处理。它适合需要回答企业相关问题的面向客户的网站。

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

想在首屏或价格区域放一个“与我们聊天”按钮？在 window 上派发 nexoply:open-chat 事件即可。由于它使用了 onClick，必须是客户端组件：

"use client";
// components/ChatButton.tsx

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

您可以在任何页面或服务器组件中使用 <ChatButton />。小组件加载后没有用于移除它的 API：如果要在某些页面（例如 /checkout）上隐藏消息按钮，请在聊天机器人 → 自定义 → 消息按钮 → 部分页面不同中添加一条设置为“不显示按钮”的页面规则。

运行 next dev，打开 http://localhost:3000，角落里就会出现聊天按钮。提一个真实的问题，例如“你们周末营业吗？”；几秒钟内，这段对话就会出现在控制台的对话中。您在控制台中所做的更改大约一分钟内就会在网站上生效，无需重新部署。

如果您的应用发送 Content-Security-Policy 响应头（例如来自 middleware 或 next.config），请在以下指令中允许 Nexoply：

• script-src https://nexoply.com：用于加载 widget.js。
• connect-src https://nexoply.com：用于聊天的请求。
• img-src https://nexoply.com：用于标志和按钮图标等图片。

• 没有按钮，且页面源代码中的 data-chatbot 为空。环境变量没有被读取：请检查 NEXT_PUBLIC_ 前缀，重启 next dev，并在托管平台上添加该变量后重新部署。
• 脚本放在了单个页面而不是布局中。请把它放进 app/layout.tsx 或 pages/_app.tsx，这样它才会在每个路由上加载。
• 标签被改动过。它必须保留 data-chatbot 属性，并且 src 中包含 widget.js。
• 被 CSP 或允许的网站设置拦截。在浏览器控制台中查找错误，并检查上面两节的内容。
• 聊天机器人已关闭。请确认启用聊天机器人开关处于打开状态。
• 广告拦截器。在极少数情况下，扩展程序会拦截聊天小组件。请在不带扩展的无痕窗口中试一试。

一切正常后，在聊天机器人 → 自定义中让它与网站相匹配：按钮图标、文字标签、配色和位置，或者使用屏幕边缘的侧边标签（例如“帮助”）；为手机设置不同的外观；以及为指定页面设置页面规则（例如只在 /pricing 上显示侧边标签）。请查看所有自定义选项和 AI 助手如何了解您的企业，比较各方案和对话限额，或阅读 React 聊天机器人组件指南和 Vue 和 Nuxt 聊天机器人指南。