给 NotionNext 博客接入 Dify AI 助手：从原理到避坑全记录

type

status

date

slug

summary

背景：先搞清楚架构

在开始之前，需要理解 NotionNext 博客的运作方式，否则后面的配置步骤会让人摸不着头脑。

Notion 的角色

Notion 在这套方案里不只是写文章的地方，它同时承担了三件事：

内容数据库：所有博客文章、页面都存在 Notion 数据库里

配置中心：博客的各种开关、参数（比如主题、评论系统、AI 配置）也存在一个 type 为 Config 的 Notion 页面里

数据源：每次有人访问博客，服务器会通过 Notion 私有 API 拉取最新数据

Vercel 的角色

Vercel 是部署平台，负责把 GitHub 仓库里的 Next.js 代码编译并运行。它的工作方式：

每次你向 GitHub 推送代码，Vercel 自动重新构建部署

支持环境变量（类似 .env 文件），注入到构建过程中

使用 ISR（增量静态再生）：页面第一次被访问时生成静态 HTML，之后定时从 Notion 拉取最新数据刷新缓存

为什么配置有两个地方

这是很多人困惑的地方。NotionNext 的配置读取优先级是：

Notion 配置页 > Vercel 环境变量 > blog.config.js 默认值

简单说：Notion 配置页优先级最高，Vercel 环境变量次之。两个地方都可以写，但有些配置在特定时机只能读到其中一个，这是后面踩坑的根源。

为什么选 Dify

NotionNext 内置了五种 AI 组件：Dify、Coze、Chatbase、WebWhiz、TianliGPT。

选 Dify 的理由：

免费版支持知识库 + URL 爬取，可以让 AI 读懂你的博客文章

可以选底层模型（接 Claude、GPT、国产模型均可）

博客代码里已内置 DifyChatbot.js 组件，理论上只需填配置

完整接入步骤

第一步：在 Dify 创建应用

访问 cloud.dify.ai 注册并登录

左侧点工作室 → 创建应用 → 选 Agent

填写系统提示词，让 AI 了解自己的定位，例如：

你是 [你的博客名] 的 AI 助手，熟悉博客的所有文章内容。
用中文回答用户问题，优先检索知识库中的相关文章。

选择底层模型（免费额度内可用 GPT-3.5 或 Claude Haiku）

第二步：创建知识库并爬取博客

左侧点知识库 → 创建知识库

选择**「从网页同步」**

填入你的博客地址，开启爬取子页面

等待爬取完成后，回到刚才创建的 Agent，在工具里添加这个知识库

第三步：获取 API Token

打开你的 Agent 应用

左侧菜单找**「API 访问」**

点**「创建密钥」**，生成格式为 app-xxxxxxxxxx 的 Token，保存好

第四步：修改代码

由于 NotionNext 的配置读取链在某些渲染时机会失效，最可靠的方式是让 DifyChatbot 直接读取环境变量，而不依赖 siteConfig 体系。

修改 components/DifyChatbot.js（完整替换）：

import { useEffect } from 'react'

const TOKEN = process.env.NEXT_PUBLIC_DIFY_CHATBOT_TOKEN
const BASE_URL = process.env.NEXT_PUBLIC_DIFY_CHATBOT_BASE_URL || 'https://udify.app'

export default function DifyChatbot() {
  useEffect(() => {
    if (!TOKEN) return

    window.difyChatbotConfig = { token: TOKEN, baseUrl: BASE_URL }

    const script = document.createElement('script')
    script.src = `${BASE_URL}/embed.min.js`
    script.id = TOKEN
    script.defer = true
    document.body.appendChild(script)

    return () => {
      document.getElementById(TOKEN)?.remove()
    }
  }, [])

  return null
}

修改 components/ExternalPlugins.js 一行：

找到：

const DIFY_CHATBOT_ENABLED = siteConfig('DIFY_CHATBOT_ENABLED', null, NOTION_CONFIG)

改为：

const DIFY_CHATBOT_ENABLED = siteConfig('DIFY_CHATBOT_ENABLED', null, NOTION_CONFIG) || process.env.NEXT_PUBLIC_DIFY_CHATBOT_ENABLED

改完后推送到 GitHub：

git add components/DifyChatbot.js components/ExternalPlugins.js
git commit -m "feat: 直接读取环境变量启用 Dify 聊天助手"
git push

第五步：在 Vercel 设置环境变量

进入 Vercel 项目 → Settings → Environment Variables，添加三个变量：

变量名	值
`NEXT_PUBLIC_DIFY_CHATBOT_ENABLED`	`true`
`NEXT_PUBLIC_DIFY_CHATBOT_TOKEN`	`app-你的Token`
`NEXT_PUBLIC_DIFY_CHATBOT_BASE_URL`	`https://udify.app`

注意：BASE_URL 填 https://udify.app，不是 https://api.dify.ai。前者是加载聊天气泡脚本的地址，后者是 API 接口地址，填错了脚本找不到，气泡不会出现。

第六步：重新部署

Vercel Deployments → 最新一条 → 右侧 ... → Redeploy。

部署完成后刷新博客，右下角出现聊天气泡即为成功。

💡

踩过的坑

坑一：配置改了没用

原因：博客有缓存机制，Notion 配置页的改动要等缓存过期或重新部署才生效。改完 Notion 后必须 Redeploy。

坑二：BASE_URL 填错

https://api.dify.ai 是后端 API 地址，不提供 embed.min.js 文件。聊天气泡脚本在 https://udify.app/embed.min.js，两者不能混用。

坑三：siteConfig 读取链在特定场景失效

siteConfig 依赖 React 的 useGlobal() Context，如果组件在某些渲染时机不在 Provider 内，useGlobal() 会抛出异常被静默捕获，整条配置链降级返回 null，导致明明填了配置却不生效。解决方式是直接读 process.env.NEXT_PUBLIC_*，绕过这个依赖。。