如何把 Inkeep AI 问答按钮接入 Nextra 文档站点？-二趣网

如何把 Inkeep AI 问答按钮接入 Nextra 文档站点？

【免费下载链接】nextraSimple, powerful and flexible site generation framework with everything you love from Next.js.项目地址: https://gitcode.com/GitHub_Trending/ne/nextra

如果你的站点基于 Nextra（nextra+nextra-theme-docs）构建，想让访问者直接在文档页面上向 AI 提问，可以把 Inkeep 的 React 组件InkeepChatButton挂到站点的根布局<body>中。接入后，按钮会出现在文档站的所有页面上，用户点击即可调用你在 Inkeep 上创建的 Web Assistant。前提条件是一个已能运行的 Nextra Docs 主题站点（即根目录有app/layout.jsx/app/layout.tsx并使用nextra-theme-docs的Layout组件），以及一个已在 Inkeep 侧创建的 Web Assistant。

1. 准备 API key 并写入环境变量

先在 Inkeep 的文档控制台中按官方流程创建一个 Web Assistant，并拿到对应的 API key（Nextra 文档中的 Ask AI 页面给出了创建入口的说明）。然后把 key 写入项目根目录的.env文件：

NEXT_PUBLIC_INKEEP_API_KEY="your_actual_api_key_here"

your_actual_api_key_here是占位符，替换为你实际拿到的 key。变量名必须以NEXT_PUBLIC_开头，这样 Next.js 才会把它暴露给客户端组件。

2. 安装 Inkeep React 组件库

在站点所在目录执行（以仓库的docs/站点为例，该依赖在 docs/package.json 中为@inkeep/cxkit-react，版本^0.5.98）：

npm i @inkeep/cxkit-react

如果你的项目用 yarn，对应yarn add @inkeep/cxkit-react。

3. 创建聊天按钮组件

新建文件inkeep-chat-button.tsx（放在app/目录或任意可被根布局引用的位置）。Nextra 官方文档给出的示例如下：

'use client' import { InkeepChatButton } from '@inkeep/cxkit-react' import type { FC } from 'react' export const ChatButton: FC = () => { return ( <InkeepChatButton aiChatSettings={{ apiKey: process.env.NEXT_PUBLIC_INKEEP_API_KEY!, // Customize your AI assistant's appearance aiAssistantAvatar: '/icon.svg', // Path to your assistant's avatar aiAssistantName: 'Nextra Assistant' // Name shown to users }} baseSettings={{ // Match your site's brand colors primaryBrandColor: '#238aff', // Sync with your site's dark/light mode colorMode: { sync: { target: 'html', attributes: ['class'], isDarkMode(attrs) { return attrs.class === 'dark' } } } }} /> ) }

其中aiAssistantAvatar指向站点public/下的头像路径、aiAssistantName是展示给用户的助手名称，两者都按你的站点自行调整；colorMode.sync的作用是让按钮跟随<html>元素的class是否为dark来切换深浅色，与 Nextra 站点现有的主题切换保持一致。

本仓库的文档站自己就用过这套组件，可以对照 docs/components/inkeep-chat-button.tsx 查看实际写法。与上面官方示例有两处差异，属于正常的项目自定义：

apiKey放在了baseSettings里而不是aiChatSettings里；
baseSettings.theme.styles中额外注入了一段 CSS（[data-theme=light] .ikp-chat-button__avatar-content { filter: invert(1); }），用于修复浅色主题下头像图标的显示。

这两处按你站点实际的头像与主题表现取舍即可，官方示例与仓库实现二选一保持自洽。

4. 把按钮挂进根布局

在根布局文件（app/layout.tsx）中导入ChatButton，并作为<body>的直接子元素渲染、放在<Layout>之外。官方示例结构：

import { Layout } from 'nextra-theme-docs' // or nextra-theme-blog or your custom theme import { Head } from 'nextra/components' import { getPageMap } from 'nextra/page-map' import type { FC } from 'react' import { ChatButton } from '../path/to/your/inkeep-chat-button' const RootLayout: FC<LayoutProps<'/'>> = async ({ children }) => { const pageMap = await getPageMap() return ( <html lang="en" dir="ltr" suppressHydrationWarning> <Head /> <body> <ChatButton /> <Layout pageMap={pageMap} // ... other layout props > {children} </Layout> </body> </html> ) } export default RootLayout

'../path/to/your/inkeep-chat-button'按你的组件实际位置替换。仓库文档站的真实根布局 docs/app/layout.tsx 中，<ChatButton />（来自@components/inkeep-chat-button）就渲染在<body>内、<Layout>之前，与本节结构一致。

注意：因为按钮挂在根布局上，它会出现在文档站的所有页面上，这是官方文档明确说明的行为（[!IMPORTANT]提示），接入前需确认这符合你的预期。

5. 启动站点并验证

运行项目的dev命令（package.json中定义为next）：

npm run dev

打开任意文档页面，页面右下角应出现aiAssistantName配置的 AI 问答按钮；点击后应弹出 Inkeep 聊天窗口并能发起提问。由于按钮位于根布局，随机切到其他文档页确认它仍然在，即可验证“全站可见”这一点符合预期。若按钮不出现，优先核对三件事：NEXT_PUBLIC_INKEEP_API_KEY是否已写入.env且重启过开发服务、@inkeep/cxkit-react是否安装成功、ChatButton是否真的渲染进了<body>。

参考路径

接入步骤原文：docs/app/docs/guide/search/ai/page.mdx
仓库内实际使用的按钮组件：docs/components/inkeep-chat-button.tsx
根布局集成位置：docs/app/layout.tsx
依赖声明：docs/package.json

【免费下载链接】nextraSimple, powerful and flexible site generation framework with everything you love from Next.js.项目地址: https://gitcode.com/GitHub_Trending/ne/nextra

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析