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

Hugo 静态站点生成器的分步指南

获取嵌入代码

平台：

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

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

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

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

步骤 2：将代码添加到主题 Partial（推荐）

将聊天机器人添加到 Hugo 站点所有页面的最佳方式是创建一个 partial：

导航到 Hugo 项目的 layouts/partials/ 目录
创建一个名为 asyntai-widget.html 的新文件
将您的 Asyntai 嵌入代码粘贴到此文件中：

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

打开主题的 baseof.html 文件（通常位于 layouts/_default/baseof.html）
在 </body> 闭合标签之前添加 partial：

    {{ partial "asyntai-widget.html" . }}
  </body>
</html>

保存文件并重新构建 Hugo 站点

提示： 使用 partial 是 Hugo 推荐的包含可重用组件的方式。此方法可确保聊天机器人出现在每个使用 baseof.html 模板的页面上，通常是站点的所有页面。

替代方法 1：添加到 Head Partial

如果您的主题有 head partial，可以在那里添加代码：

找到主题的 head partial（通常位于 layouts/partials/head.html）
如果不存在，请在项目根目录创建 layouts/partials/head.html
将您的 Asyntai 嵌入代码添加到此文件：

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

确保 baseof.html 在 <head> 部分中包含了此 partial：

<head>
  {{ partial "head.html" . }}
</head>

注意： 如果主题已经有包含现有内容的 head.html partial，只需将 Asyntai 代码追加到其中。不要替换现有内容。

替代方法 2：使用静态文件夹和自定义 JavaScript

使用 Hugo 静态文件夹的更模块化方式：

导航到 Hugo 项目的 static/js/ 目录
如果目录不存在则创建它
创建一个名为 asyntai-loader.js 的新文件
添加以下代码以加载小部件：

// static/js/asyntai-loader.js
(function() {
  var 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);
})();

在 baseof.html 或 footer partial 的 </body> 之前引用此文件：

<script src="{{ "js/asyntai-loader.js" | relURL }}"></script>
</body>

提示： static/ 目录中的文件会原样复制到已发布站点的根目录。relURL 函数会为您的部署生成正确的相对路径。

替代方法 3：Hugo 配置（config.toml/yaml）

对于一些通过配置支持自定义脚本的 Hugo 主题：

# config.toml
[params]
  customJS = ["https://asyntai.com/static/js/chat-widget.js"]

# Or in config.yaml
params:
  customJS:
    - https://asyntai.com/static/js/chat-widget.js

注意： 此方法仅在主题支持 customJS 参数时有效。请查看主题文档。您可能还需要通过主题自定义添加 data-asyntai-id 属性。

替代方法 4：Front Matter（页面特定）

仅在特定页面上添加聊天机器人：

在页面的 front matter 中添加自定义参数：

---
title: "My Page"
asyntaiWidget: true
---

在 baseof.html 或 partial 中添加条件逻辑：

{{ if .Params.asyntaiWidget }}
  <script async src="https://asyntai.com/static/js/chat-widget.js" data-asyntai-id="YOUR_WIDGET_ID"></script>
{{ end }}

提示： 此方法可让您精细控制哪些页面包含聊天机器人。对于只想在特定部分显示小部件的文档站点非常有用。

替代方法 5：覆盖主题布局

在不修改主题文件的情况下覆盖主题布局：

从 themes/your-theme/layouts/_default/ 复制主题的 baseof.html
将其粘贴到项目的 layouts/_default/baseof.html
在 </body> 闭合标签之前添加您的 Asyntai 嵌入代码
保存并重新构建站点

重要提示： 当您覆盖主题文件时，主题更新时这些文件不会自动获得更新。此方法提供完全控制，但需要更多维护。建议使用 partial 以便更轻松地进行主题更新。

步骤 3：构建并部署

添加代码后，构建您的 Hugo 站点：

# Build the site
hugo

# Or build with specific environment
hugo --environment production

# For development preview
hugo server

生成的站点将在 public/ 目录中
将此目录部署到您的托管平台（Netlify、Vercel、GitHub Pages 等）

提示： 在开发期间，使用 hugo server 在 http://localhost:1313 本地预览站点。聊天机器人应出现在所有页面的右下角。

步骤 4：验证安装

部署 Hugo 站点后，在新的浏览器标签页中打开它。您应该能在右下角看到聊天小部件按钮。点击它确保它能正常打开和运行。

看不到小部件？ 确保在进行更改后使用 hugo 命令重新构建了站点。检查是否已将 YOUR_WIDGET_ID 替换为仪表板中的实际小部件 ID。清除浏览器缓存或在无痕模式下查看。如果使用 CDN，您可能需要使缓存失效。按 F12 打开浏览器控制台检查是否有 JavaScript 错误。