把 Dify 聊天机器人嵌入网站

这篇适合谁

适合已经在 Dify 里发布了 Web 应用、想把它放进自己网站的人。读完你能选出合适的嵌入方式，配好聊天气泡或 iframe，并知道出问题时先查哪里。

嵌入的是同一个应用

嵌入不是另一种发布方式。Dify 发布应用后会得到一个 Web 应用 URL，嵌入网站的仍是同一个应用，只是呈现在你的页面里，而不是作为独立页面出现^[1]。应用配置的改动会自动应用到所有嵌入位置^[1]。

Dify 提供四种呈现方式：聊天气泡组件、iframe、JavaScript 控制（可自定义样式和行为），以及能适配不同展示形式的响应式设计^[1]。实际中用得最多的是前两种。

第一步：拿到嵌入令牌

在 Dify 应用里打开访问入口标签页，在 Web 应用卡片上点击嵌入网站，就能找到这个应用唯一的令牌^[1]。

聊天气泡怎么配

聊天气泡把 Web 应用显示为一个浮动按钮。访客点击后，应用以浮层形式打开，无需离开当前页面^[1]。

配置写在 window.difyChatbotConfig 对象里。token 是必填项，填的是 Dify 给出的应用令牌^[1]：

window.difyChatbotConfig = {
    // 必需：来自 Dify 的应用令牌
    token: 'YOUR_TOKEN',

这是配置的开头部分，完整对象还包括其他可选项。baseUrl 会根据 isDev 自动设置，示例中的值是 https://udify.app。draggable 控制访客能否拖动按钮，dragAxis 可以取 'x'、'y' 或 'both'^[1]。

containerProps 用来设置气泡的位置和样式，className 可以挂上自定义 CSS 类。示例把按钮放在距右边和底边各 20px 的位置^[1]：

    containerProps: {
        style: {
            right: '20px',
            bottom: '20px'
        },
        className: 'custom-chat-button'
    },

inputs 用来预填用户上下文，键名必须是你 Dify 应用里的变量名。示例传入了 name 和 department^[1]：

    inputs: {
        name: "John Doe",          // 来自你的 Dify 应用的变量名
        department: "Support"
    },

systemVariables 放用于追踪的系统变量，例如 user_id 和 conversation_id；userVariables 放用户资料，例如头像地址和姓名^[1]。

四种输入类型的处理规则不同。text-input 和 paragraph 接受任何值，超过最大长度的字符串会被截断。number 接受数字或数字字符串，字符串会用 Number 函数转成数字。options 可以接受任何值，但必须匹配预先配置的某个选项^[1]。

用 embed.js 脚本创建 iframe 时，每个输入值会先经过 GZIP 压缩和 base64 编码，然后再附加到 URL 上^[1]。

Iframe 怎么嵌

Iframe 把 Web 应用直接放进页面内容里，访客不用先点按钮就能看到它。src 填 https://udify.app/chatbot/ 加上应用令牌即可，把 YOUR_APP_TOKEN 换成你的令牌^[1]：

<iframe
  src="https://udify.app/chatbot/YOUR_APP_TOKEN"
  width="100%"
  height="600"
  frameborder="0">
</iframe>

Iframe 的优点是：始终可见，功能与应用本身保持一致，以页面原生内容的形式呈现，只需要 HTML，不需要 JavaScript 配置^[1]。

怎么选

• 客户支持应用：聊天气泡更合适。平时不打扰浏览，需要时随时可用^[1]。
• 表单和 Workflow 应用：应用是页面主体时，用 iframe^[1]。
• 产品演示：在着陆页用 iframe，访客可以直接体验 AI 能力^[1]。
• 多页面集成：全站每个页面都要访问同一个应用时，用聊天气泡，一段嵌入代码就能覆盖所有页面^[1]。

自定义按钮样式

聊天气泡按钮可以用 CSS 变量改样式。--dify-chatbot-bubble-button-bg-color 控制背景色，默认 #155EEF；宽度和高度变量默认 50px，圆角变量默认 25px^[1]。按钮距底部和右侧的距离由 --dify-chatbot-bubble-button-bottom 和 --dify-chatbot-bubble-button-right 控制，默认都是 1rem；悬停效果由 --dify-chatbot-bubble-button-hover-transform 控制，默认 scale(1.1)^[1]。

要把背景色改成 #ABCDEF，加入这段 CSS^[1]：

#dify-chatbot-bubble-button {
    --dify-chatbot-bubble-button-bg-color: #ABCDEF;
}

常见问题

气泡不显示。 先确认令牌与应用「访问入口」标签页「嵌入网站」里显示的一致，再检查配置是否在嵌入脚本之前加载，最后看浏览器控制台有没有 JavaScript 错误^[1]。

Iframe 加载不出来。 确认 URL 里的令牌正确；检查网站的内容安全策略（CSP）是否允许 iframe 内容；网站和 Dify 应用都应使用 HTTPS^[1]。

改了配置没有生效。 Web 应用必须先发布才能嵌入。修改配置后要重新发布，变更才会进入嵌入版本^[1]。

下一步

嵌入的完整说明，包括各种 CSS 变量和输入类型，可以去 Dify 文档的「嵌入 Web 应用」页面查阅^[1]。

本文改编自 Dify 文档中的「嵌入 Web 应用」页面^[1]，原文以 CC BY 4.0 许可证发布。