如何将 Asyntai AI 聊天机器人添加到 Docusaurus

Docusaurus 文档站点的分步指南

获取嵌入代码

平台：

步骤1：获取您的嵌入代码

首先，前往您的 Asyntai 仪表板并向下滚动到"嵌入代码"部分。复制您的专属嵌入代码，格式如下：

<script async src="https://asyntai.com/static/js/chat-widget.js" data-asyntai-id="YOUR_WIDGET_ID"></script>

注意： 以上代码仅为示例。您必须从仪表板复制您自己的专属嵌入代码，因为其中包含您的个人小部件 ID。

步骤 2：将脚本添加到 docusaurus.config.js（推荐）

将聊天机器人添加到 Docusaurus 站点所有页面的最佳方式是通过配置文件：

在代码编辑器中打开 Docusaurus 项目
在项目根目录找到并打开 docusaurus.config.js 文件
找到 const config = { } 对象
添加或更新 scripts 字段以包含您的 Asyntai 小部件：

const config = {
  // ... other config options

  scripts: [
    // Other scripts if any
    {
      src: 'https://asyntai.com/static/js/chat-widget.js',
      'data-asyntai-id': 'YOUR_WIDGET_ID',
      async: true,
    },
  ],

  // ... rest of config
};

保存 docusaurus.config.js 文件
运行 npm run build 或 yarn build 重新构建站点
如果在本地运行，请重启开发服务器

提示： scripts 字段接受一个 JavaScript 来源数组。脚本标签将自动插入到每个页面的 HTML head 中。这是 Docusaurus 站点最简洁、最易维护的方法。

替代方法 1：字符串格式（更简单的语法）

如果您偏好更简单的方式，可以在 scripts 数组中使用字符串格式：

const config = {
  scripts: [
    'https://asyntai.com/static/js/chat-widget.js',
  ],
};

注意： 使用字符串格式时，您需要修改脚本 URL 以将小部件 ID 作为查询参数包含在内，或使用步骤 2 中显示的对象格式，该格式允许您直接设置 data-asyntai-id 属性。

替代方法 2：自定义 Head 标签

您也可以使用 docusaurus.config.js 中的 headTags 字段添加脚本：

const config = {
  headTags: [
    {
      tagName: 'script',
      attributes: {
        src: 'https://asyntai.com/static/js/chat-widget.js',
        'data-asyntai-id': 'YOUR_WIDGET_ID',
        async: true,
      },
    },
  ],
};

提示： headTags 字段可以更精确地控制插入 <head> 部分的 HTML 标签。此方法在功能上等同于使用 scripts 字段。

替代方法 3：自定义 HTML 模板（高级）

对于需要完全控制 HTML 模板的高级用户：

创建新目录：src/theme（如果不存在）
创建文件：src/theme/Root.js
添加以下代码以动态注入脚本：

import React, { useEffect } from 'react';

export default function Root({children}) {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://asyntai.com/static/js/chat-widget.js';
    script.setAttribute('data-asyntai-id', 'YOUR_WIDGET_ID');
    script.async = true;
    document.head.appendChild(script);

    return () => {
      // Cleanup when component unmounts
      document.head.removeChild(script);
    };
  }, []);

  return <>{children}</>;
}

保存文件并重新构建站点

重要提示： Root.js 组件包裹整个应用程序。此高级方法仅在需要自定义 JavaScript 逻辑或有配置文件方法无法满足的特定需求时使用。

替代方法 4：Swizzle Footer 组件

您可以自定义页脚以包含脚本：

运行 swizzle 命令：npm run swizzle @docusaurus/theme-classic Footer -- --eject
这将在 src/theme/Footer/ 中创建 Footer 组件的副本
编辑 Footer 组件以包含您的脚本标签
在页脚的闭合标签之前添加脚本
保存并重新构建站点

注意： Swizzling 让您完全控制 Docusaurus 组件，但这意味着您需要自己维护该组件。Docusaurus 的更新不会自动更新被 swizzle 的组件。

步骤 3：构建并部署

添加代码后，构建并部署您的 Docusaurus 站点：

# Build the site
npm run build

# Or with Yarn
yarn build

# Deploy to your hosting platform
# (Vercel, Netlify, GitHub Pages, etc.)

提示： 开发期间，运行 npm start 或 yarn start 在本地预览更改。聊天机器人应该出现在所有页面的右下角。

步骤 4：验证安装

部署更改后，在新的浏览器标签页中打开您的文档站点。您应该会在右下角看到聊天小部件按钮。点击它以确保能正常打开和使用。

看不到小部件？ 确保在更改后已重新构建站点。检查是否已将 YOUR_WIDGET_ID 替换为仪表板中的实际小部件 ID。清除浏览器缓存或在无痕模式下查看。打开浏览器控制台（F12）检查是否有 JavaScript 错误。