FastGPT 官方文档站开发指南基于 Fumadocs 的 MDX 写作、i18n 与本地部署全实践【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT导读本文围绕 FastGPT 仓库中 document/README.md 所描述的官方文档站展开完整讲解如何在本地运行这套基于 Fumadocs 框架的文档项目、如何以 MDX 格式书写文档并注册页面、如何维护中英双语 i18n以及如何通过内置组件实现 Alert 高亮、Tabs 切换、页面重定向和带 UTM 归因的官网跳转链接。读完本文你将掌握 FastGPT 文档站的完整开发工作流并理解其背后的组件实现与配置原理可以直接上手为文档站新增页面、导航和重定向规则。一、文档站概览基于 Fumadocs 的官方文档项目FastGPT 的官方文档位于仓库的 document 目录是一个独立于主应用projects/app运行的 Next.js 站点底层采用Fumadocs文档框架fumadocs-core、fumadocs-mdx、fumadocs-ui。从 document/package.json 可以看到其核心技术栈Next.js 15 React 19配合next dev --turbo启动开发服务器Fumadocs 15fumadocs-core、fumadocs-mdx、fumadocs-ui负责 MDX 内容收集、文档路由与 UI 组件MDX作为文档书写格式支持在 Markdown 中直接使用自定义 React 组件lucide-react提供 frontmatter 中icon字段所需的图标mermaid支持在文档中渲染流程图见 source.config.ts 中的remarkMermaid插件textlint 中文技术写作规则提供文档写作质量校验lint-doc:text、format-doc脚本。文档内容全部存放在 document/content 目录下按guide、dataset、self-host、openapi、plugin、faq等主题组织每个目录下既有.mdx正文文件也有控制侧边栏与页面顺序的meta.json。从源码结构看文档站还内置了一批定制组件位于 document/components/docs包括Alert、Tabs、Redirect、FastGPTLink、MermaidDiagram、UpgradeVersionTimeline等这些正是书写文档时的扩展语法。二、环境准备与本地运行2.1 配置环境变量运行文档站前需要先配置环境变量。在document目录下创建.env.local文件写入FASTGPT_HOME_DOMAINhttps://fastgpt.io # 只填写 origin不携带路径或查询参数注意两个关键约束只填写 origin协议 域名不要携带路径或查询参数该变量决定文档中FastGPTLink组件生成的官网跳转链接指向哪个站点。该变量的实际解析逻辑在 document/lib/fastgpt-home-url.tsgetFastGPTHomeOrigin会优先读取NEXT_PUBLIC_FASTGPT_HOME_DOMAIN其次读取FASTGPT_HOME_DOMAIN两者都未配置时回退到默认值https://fastgpt.io。解析时会用new URL(value).origin做归一化即使误填了带路径的值也会被截断为 origin——这是源码层面保证只填写 origin约束的兜底逻辑。此外文档搜索等场景还会基于该 origin 推导出doc.子域getFastGPTDocsOrigin因此请务必保证该变量准确。2.2 安装依赖并启动在 FastGPT 仓库根目录本仓库即根目录执行pnpm install pnpm dev其中pnpm dev会进入document包的开发脚本next dev --turbo见 document/package.json。安装过程中会执行postinstall钩子fumadocs-mdx将content目录下的 MDX 文件编译为可被 Next.js 使用的模块这是 Fumadocs 内容收集的关键一步。启动成功后文档站默认运行在http://localhost:3000。仓库采用 pnpm workspace 管理pnpm install会同时安装文档站与其余packages的依赖若只想跑文档也可直接在document目录内执行安装与启动。2.3 常用脚本一览脚本命令作用开发pnpm dev启动 Turbo 模式开发服务器默认 3000 端口构建pnpm build执行next build生产构建启动pnpm start启动生产服务器文档格式化pnpm format-doctextlint 修复 prettier 格式化所有 MDX文档文本校验pnpm lint-doc:texttextlint 检查中文技术写作规范初始化文档时间pnpm initDocTime运行script/initDocTime.js生成文档最后修改时间生成目录pnpm initDocToc运行script/generateToc.js生成 TOC文档引用检查pnpm checkDocRefs运行script/checkDocRefs.js检查文档内引用是否失效清理失效图片pnpm removeInvalidImg运行script/removeInvalidImg.js清理无效图片引用三、书写文档MDX 格式与 frontmatter3.1 文件格式与元数据文档采用MDX格式与普通 Markdown 大体一致但可以直接在正文中引用 React 组件。文档的元数据frontmatter目前只支持title、description和icon三个字段参考示例--- title: FastGPT 文档 description: FastGPT 官方文档 icon: menu # icon 采用 lucide-react 第三方库。 ---其中icon字段取值来自lucide-react图标库的图标名称。需要说明的是这只是 README 中约定的基础三字段。从 document/source.config.ts 可以看到文档站实际通过 Zod 对 frontmatter 做了扩展还支持releaseTimeISO 日期、sidebarTag侧边栏标签、upgradeTags升级标签数组等可选字段供版本发布与升级时间线等场景使用。也就是说在书写基础文档时使用title/description/icon即可涉及版本升级类文档时还可利用releaseTime、upgradeTags增强表现。3.2 内置组件Alert 高亮块Alert用于在文档中插入带图标、带语义色彩的高亮提示块书写语法为import { Alert } from /components/docs/Alert; # 高亮块组件 Alert icon contextsuccess 快速开始体验 - 海外版FastGPTLink campaigndocs_getting_started contentcloud_entry_io siteio{https://fastgpt.io}/FastGPTLink - 中国大陆FastGPTLink campaigndocs_getting_started contentcloud_entry_cn sitecn{https://fastgpt.cn}/FastGPTLink /Alertcontext支持四种语义取值对应不同的配色方案见 document/components/docs/Alert.tsxcontext视觉含义配色特征浅色/深色success成功、推荐操作绿色边框 / teal 描边warning警告、注意黄色边框 / indigo 描边error错误、禁止红色边框 / 红色描边info一般信息默认值蓝色边框 / blue 描边icon接受任意 ReactNode可传 emoji也可传图标组件。该组件实现了context默认值info并在 hover 时有阴影过渡效果。3.3 内置组件Redirect 重定向Redirect用于让当前文档页面自动跳转到另一个文档常用于本文档已迁移/已合并的场景import { Redirect } from /components/docs/Redirect # 重定向组件如果你希望用户点击这个文件跳转到别的文件的话 Redirect to/docs/self-host/deploy/docker/#faq /其实现位于 document/components/docs/Redirect.tsx核心逻辑有三点兼容带语言前缀的路径removeLocalePrefix会先剥离路径中的语言段如/zh-CN/...再执行跳转兼容.mdx后缀normalizeDocPath会去掉.mdx或.en.mdx后缀支持以源码文件路径形式书写to参数自动补语言前缀跳转目标最终会经过getLocalizedPath加上当前语言前缀保证中英文环境各自跳到正确版本。to参数既支持以/开头的绝对路径也支持相对当前文档的路径内部会基于当前 pathname 做 URL 归一化。3.4 内置组件Tabs 多标签内容Tabs/Tab组件用于在同一位置展示多份可切换内容如不同编程语言的代码示例import { Tabs } from /components/docs/Tabs; # tabs 组件用法 Tabs items{[Javascript, Rust]} Tab valueJavascriptJavascript is weird/Tab Tab valueRustRust is fast/Tab /Tabs实现上document/components/docs/Tabs.tsxTabs接收items数组作为标签列表通过React.Children.toArray收集所有Tab子元素用useState维护当前激活标签索引点击标签按钮即切换展示对应内容Tab本身只是一个承载children的纯容器组件。注意示例中既有items属性又有Tab的title属性两种写法都可用于标识标签文字。3.5 内置组件FastGPTLink 官网跳转链接文档中凡是跳转 FastGPT 官网云服务、商业咨询、产品入口等的链接统一使用FastGPTLink组件而不是裸的a标签import FastGPTLink from /components/docs/linkFastGPT; # FastGPT 跳转链接组件根据域名环境变量和传入的归因参数生成链接 本文档介绍了如何设置开发环境以构建和测试 FastGPTLink campaigndocs_self_host_dev contentintro_product_linkFastGPT/FastGPTLink。该组件会根据环境变量和传入的归因参数自动生成带 UTM 参数的官网链接其核心实现在 document/lib/fastgpt-home-url.tssite属性决定目标域名io固定指向https://fastgpt.iocn固定指向https://fastgpt.cn默认值configured则使用环境变量FASTGPT_HOME_DOMAIN配置的 origin自动附加 UTM 参数无论site取何值都会固定添加utm_sourcedocs与utm_mediumreferral并拼接调用方传入的utm_campaign与utm_content组件本身document/components/docs/linkFastGPT.tsx是 Client Component用useMemo缓存 URL 计算结果并内置了默认蓝色链接样式与 hover 下划线效果React.memo包裹以避免不必要的重渲染。为什么必须用 FastGPTLink因为归因参数是强制附加的使用裸链接会丢失utm_sourcedocs与utm_mediumreferral导致官网无法统计文档渠道的流量来源。详见下文 UTM 归因规范。3.6 UTM 归因规范新增跳转 FastGPT 官网的链接时必须同步登记并复用 document/UTM_ATTRIBUTION.md 中定义的utm_campaign和utm_content核心约定如下域名环境变量FASTGPT_HOME_DOMAIN只配置 origin如https://fastgpt.io或https://fastgpt.cn不能携带路径或查询参数商机来源商机表单的业务来源使用独立的source参数不使用utm_source作为提交来源source由官网 Cookie 保留并写入 CRM 商机UTM 参数仍保留用于匿名渠道分析文档内跳转固定参数utm_sourcedocs、utm_mediumreferral由组件自动附加页面与链接位置使用utm_campaign/utm_content区分。常用的utm_campaign/utm_content组合完整清单见 UTM 归因规范页面utm_campaign链接位置utm_content快速了解 FastGPTdocs_getting_started国际版入口cloud_entry_io快速了解 FastGPTdocs_getting_started中国大陆版入口cloud_entry_cn云服务介绍docs_cloud_intro国际版入口cloud_entry_io云服务介绍docs_cloud_intro中国大陆版入口cloud_entry_cn云服务 FAQdocs_cloud_faq国际版登录帮助login_help_io云服务 FAQdocs_cloud_faq中国大陆版登录帮助login_help_cn本地开发docs_self_host_dev文档开头产品链接intro_product_link本地开发docs_self_host_dev前置环境产品链接prerequisites_product_link文档导航docs_navigation商业咨询入口business_consultation命名规范同一页面或同一推广主题复用同一个utm_campaign用不同utm_content区分具体链接位置新增页面时使用稳定、可读的小写下划线命名不要把文案或时间写入参数。DOCS_UTM_CAMPAIGNS常量在 document/lib/fastgpt-home-url.ts 中也有集中定义可作为类型与取值的双重约束。四、页面注册meta.json 的 pages 字段在书写完 MDX 文档后必须在对应目录的meta.json文件的pages字段合适位置添加自己的文件名否则文档不会出现在导航中。例如在content默认所有文档的根目录下的introduction目录中书写了一个hello.mdx文件则需要去该introduction目录下的meta.json添加{ title: FastGPT Docs, root: true, pages: [[Handshake][联系我们](https://fastgpt.cn/zh/contact?sourcedocsutm_sourcedocsutm_mediumreferralutm_campaigndocs_navigationutm_contentbusiness_consultation), index, guide, development, FAQ, shopping_cart, community, hello], order: 1 }两个要点pages数组的顺序就是最终文档的展示顺序。在上例中hello原本没有添加后hello文档会展示在introduction目录导航的最后pages中的条目可以是纯文件名也可以是 Markdown 格式的外部链接条目如上例中的[Handshake]联系我们用于在导航中插入官网外链。该外链同样遵循 UTM 归因规范携带了utm_campaigndocs_navigation、utm_contentbusiness_consultation等参数。meta.json中的order字段控制该目录在上级导航中的排序位置root: true标记其为根级分组。这里的metaschema 由 Fumadocs 的metaSchema统一校验见 document/source.config.ts。五、i18n 双语维护文档站的国际化遵循默认文件 语言后缀文件的约定content下的所有.mdx文件为默认语言文件当前默认语言为中文.en.mdx文件为英文翻译文件。例如将hello.mdx翻译后写成hello.en.mdx即可同时在对应目录的meta.en.json的pages字段中写下对应的文件名以支持英文导航。i18n 的核心配置在 document/lib/i18n.tsexport const i18n: I18nConfig { defaultLanguage: zh-CN, languages: [zh-CN, en], hideLocale: never };defaultLanguage: zh-CN默认语言为简体中文languages: [zh-CN, en]支持简体中文与英文两种语言hideLocale: neverURL 中始终保留语言前缀如/zh-CN/guide/...、/en/guide/...这也是getLocalizedPathdocument/lib/i18n.ts返回带前缀路径的依据。在此基础上文档站还提供了语言感知的导航工具document/lib/localized-navigation.tsuseCurrentLang()从当前 pathname 的第一个路径段解析语言解析不到时回退到默认语言useLocalizedPath(path)把基础路径转换为带当前语言前缀的路径useLocalizedRouter()包装 Next.jsuseRouter使push/replace/prefetch自动附加语言前缀。因此自定义组件内需要跳转文档内页面时应优先使用这些工具避免硬编码语言前缀。六、特殊配置导航栏与重定向6.1 增加顶层导航栏如需在文档站顶部导航栏新增栏目编辑FastGPT/document/app/[lang]/docs/layout.tsx文件在其中新增导航项即可。该布局文件是所有文档页面的顶层布局[lang]动态段对应 i18n 的语言前缀导航配置变更会作用于中英文两套站点。注意本文所述路径为仓库内 document/app/[lang]/docs/layout.tsx。6.2 兜底重定向404 → 首页对于不存在的页面文档站在 document/components/docs/not-found.tsx 中实现了全局兜底当页面未找到时NotFound组件会通过window.location.replace将用户重定向到defaultHomePath即/guide/getting-started定义于 document/lib/i18n.ts从而避免出现 404 死链。新增重定向规则例如把某个废弃文档指向新文档就在此文件中维护。七、进阶理解文档构建管线除 README 介绍的日常开发流程外从源码可以进一步看到文档站完整的构建管线内容收集fumadocs-mdx通过 document/source.config.ts 中的defineDocs({ dir: content, ... })收集content目录下的全部 MDX 与meta.json并以 Zod 校验 frontmatter基础title/description/icon之外还支持releaseTime、sidebarTag、upgradeTags扩展字段MDX 预处理mdxOptions.remarkPlugins注册了remarkMermaid插件它会遍历 MDX AST把所有lang mermaid的代码块转换为MermaidDiagramJSX 节点从而在文档中直接渲染流程图文档辅助数据仓库内 document/data/doc-last-modified.json 记录文档最后修改时间由initDocTime脚本生成供lastModifiedTime: git之外的时间展示使用script/checkDocRefs.js用于校验文档引用有效性script/removeInvalidImg.js清理失效图片引用——这些是保持文档质量的自检机制搜索支持依赖orama/orama与orama/tokenizers为文档站提供全文检索能力见 document/package.json。结语FastGPT 文档站虽然是一个文档项目但其工程化程度并不亚于主应用基于 Fumadocs 的内容收集管线、可扩展的 frontmatter schema、围绕官网转化打造的 UTM 归因体系、完备的中英双语 i18n 机制以及 Alert / Tabs / Redirect / FastGPTLink 等定制组件共同构成了一个可维护、可检索、可追踪来源的官方技术文档平台。无论是新增一篇普通指南还是调整导航结构、新增重定向、维护多语言都可以在上文的工作流中找到对应操作路径与源码依据。【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
FastGPT 官方文档站开发指南基于 Fumadocs 的 MDX 写作、i18n 与本地部署全实践【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT导读本文围绕 FastGPT 仓库中 document/README.md 所描述的官方文档站展开完整讲解如何在本地运行这套基于 Fumadocs 框架的文档项目、如何以 MDX 格式书写文档并注册页面、如何维护中英双语 i18n以及如何通过内置组件实现 Alert 高亮、Tabs 切换、页面重定向和带 UTM 归因的官网跳转链接。读完本文你将掌握 FastGPT 文档站的完整开发工作流并理解其背后的组件实现与配置原理可以直接上手为文档站新增页面、导航和重定向规则。一、文档站概览基于 Fumadocs 的官方文档项目FastGPT 的官方文档位于仓库的 document 目录是一个独立于主应用projects/app运行的 Next.js 站点底层采用Fumadocs文档框架fumadocs-core、fumadocs-mdx、fumadocs-ui。从 document/package.json 可以看到其核心技术栈Next.js 15 React 19配合next dev --turbo启动开发服务器Fumadocs 15fumadocs-core、fumadocs-mdx、fumadocs-ui负责 MDX 内容收集、文档路由与 UI 组件MDX作为文档书写格式支持在 Markdown 中直接使用自定义 React 组件lucide-react提供 frontmatter 中icon字段所需的图标mermaid支持在文档中渲染流程图见 source.config.ts 中的remarkMermaid插件textlint 中文技术写作规则提供文档写作质量校验lint-doc:text、format-doc脚本。文档内容全部存放在 document/content 目录下按guide、dataset、self-host、openapi、plugin、faq等主题组织每个目录下既有.mdx正文文件也有控制侧边栏与页面顺序的meta.json。从源码结构看文档站还内置了一批定制组件位于 document/components/docs包括Alert、Tabs、Redirect、FastGPTLink、MermaidDiagram、UpgradeVersionTimeline等这些正是书写文档时的扩展语法。二、环境准备与本地运行2.1 配置环境变量运行文档站前需要先配置环境变量。在document目录下创建.env.local文件写入FASTGPT_HOME_DOMAINhttps://fastgpt.io # 只填写 origin不携带路径或查询参数注意两个关键约束只填写 origin协议 域名不要携带路径或查询参数该变量决定文档中FastGPTLink组件生成的官网跳转链接指向哪个站点。该变量的实际解析逻辑在 document/lib/fastgpt-home-url.tsgetFastGPTHomeOrigin会优先读取NEXT_PUBLIC_FASTGPT_HOME_DOMAIN其次读取FASTGPT_HOME_DOMAIN两者都未配置时回退到默认值https://fastgpt.io。解析时会用new URL(value).origin做归一化即使误填了带路径的值也会被截断为 origin——这是源码层面保证只填写 origin约束的兜底逻辑。此外文档搜索等场景还会基于该 origin 推导出doc.子域getFastGPTDocsOrigin因此请务必保证该变量准确。2.2 安装依赖并启动在 FastGPT 仓库根目录本仓库即根目录执行pnpm install pnpm dev其中pnpm dev会进入document包的开发脚本next dev --turbo见 document/package.json。安装过程中会执行postinstall钩子fumadocs-mdx将content目录下的 MDX 文件编译为可被 Next.js 使用的模块这是 Fumadocs 内容收集的关键一步。启动成功后文档站默认运行在http://localhost:3000。仓库采用 pnpm workspace 管理pnpm install会同时安装文档站与其余packages的依赖若只想跑文档也可直接在document目录内执行安装与启动。2.3 常用脚本一览脚本命令作用开发pnpm dev启动 Turbo 模式开发服务器默认 3000 端口构建pnpm build执行next build生产构建启动pnpm start启动生产服务器文档格式化pnpm format-doctextlint 修复 prettier 格式化所有 MDX文档文本校验pnpm lint-doc:texttextlint 检查中文技术写作规范初始化文档时间pnpm initDocTime运行script/initDocTime.js生成文档最后修改时间生成目录pnpm initDocToc运行script/generateToc.js生成 TOC文档引用检查pnpm checkDocRefs运行script/checkDocRefs.js检查文档内引用是否失效清理失效图片pnpm removeInvalidImg运行script/removeInvalidImg.js清理无效图片引用三、书写文档MDX 格式与 frontmatter3.1 文件格式与元数据文档采用MDX格式与普通 Markdown 大体一致但可以直接在正文中引用 React 组件。文档的元数据frontmatter目前只支持title、description和icon三个字段参考示例--- title: FastGPT 文档 description: FastGPT 官方文档 icon: menu # icon 采用 lucide-react 第三方库。 ---其中icon字段取值来自lucide-react图标库的图标名称。需要说明的是这只是 README 中约定的基础三字段。从 document/source.config.ts 可以看到文档站实际通过 Zod 对 frontmatter 做了扩展还支持releaseTimeISO 日期、sidebarTag侧边栏标签、upgradeTags升级标签数组等可选字段供版本发布与升级时间线等场景使用。也就是说在书写基础文档时使用title/description/icon即可涉及版本升级类文档时还可利用releaseTime、upgradeTags增强表现。3.2 内置组件Alert 高亮块Alert用于在文档中插入带图标、带语义色彩的高亮提示块书写语法为import { Alert } from /components/docs/Alert; # 高亮块组件 Alert icon contextsuccess 快速开始体验 - 海外版FastGPTLink campaigndocs_getting_started contentcloud_entry_io siteio{https://fastgpt.io}/FastGPTLink - 中国大陆FastGPTLink campaigndocs_getting_started contentcloud_entry_cn sitecn{https://fastgpt.cn}/FastGPTLink /Alertcontext支持四种语义取值对应不同的配色方案见 document/components/docs/Alert.tsxcontext视觉含义配色特征浅色/深色success成功、推荐操作绿色边框 / teal 描边warning警告、注意黄色边框 / indigo 描边error错误、禁止红色边框 / 红色描边info一般信息默认值蓝色边框 / blue 描边icon接受任意 ReactNode可传 emoji也可传图标组件。该组件实现了context默认值info并在 hover 时有阴影过渡效果。3.3 内置组件Redirect 重定向Redirect用于让当前文档页面自动跳转到另一个文档常用于本文档已迁移/已合并的场景import { Redirect } from /components/docs/Redirect # 重定向组件如果你希望用户点击这个文件跳转到别的文件的话 Redirect to/docs/self-host/deploy/docker/#faq /其实现位于 document/components/docs/Redirect.tsx核心逻辑有三点兼容带语言前缀的路径removeLocalePrefix会先剥离路径中的语言段如/zh-CN/...再执行跳转兼容.mdx后缀normalizeDocPath会去掉.mdx或.en.mdx后缀支持以源码文件路径形式书写to参数自动补语言前缀跳转目标最终会经过getLocalizedPath加上当前语言前缀保证中英文环境各自跳到正确版本。to参数既支持以/开头的绝对路径也支持相对当前文档的路径内部会基于当前 pathname 做 URL 归一化。3.4 内置组件Tabs 多标签内容Tabs/Tab组件用于在同一位置展示多份可切换内容如不同编程语言的代码示例import { Tabs } from /components/docs/Tabs; # tabs 组件用法 Tabs items{[Javascript, Rust]} Tab valueJavascriptJavascript is weird/Tab Tab valueRustRust is fast/Tab /Tabs实现上document/components/docs/Tabs.tsxTabs接收items数组作为标签列表通过React.Children.toArray收集所有Tab子元素用useState维护当前激活标签索引点击标签按钮即切换展示对应内容Tab本身只是一个承载children的纯容器组件。注意示例中既有items属性又有Tab的title属性两种写法都可用于标识标签文字。3.5 内置组件FastGPTLink 官网跳转链接文档中凡是跳转 FastGPT 官网云服务、商业咨询、产品入口等的链接统一使用FastGPTLink组件而不是裸的a标签import FastGPTLink from /components/docs/linkFastGPT; # FastGPT 跳转链接组件根据域名环境变量和传入的归因参数生成链接 本文档介绍了如何设置开发环境以构建和测试 FastGPTLink campaigndocs_self_host_dev contentintro_product_linkFastGPT/FastGPTLink。该组件会根据环境变量和传入的归因参数自动生成带 UTM 参数的官网链接其核心实现在 document/lib/fastgpt-home-url.tssite属性决定目标域名io固定指向https://fastgpt.iocn固定指向https://fastgpt.cn默认值configured则使用环境变量FASTGPT_HOME_DOMAIN配置的 origin自动附加 UTM 参数无论site取何值都会固定添加utm_sourcedocs与utm_mediumreferral并拼接调用方传入的utm_campaign与utm_content组件本身document/components/docs/linkFastGPT.tsx是 Client Component用useMemo缓存 URL 计算结果并内置了默认蓝色链接样式与 hover 下划线效果React.memo包裹以避免不必要的重渲染。为什么必须用 FastGPTLink因为归因参数是强制附加的使用裸链接会丢失utm_sourcedocs与utm_mediumreferral导致官网无法统计文档渠道的流量来源。详见下文 UTM 归因规范。3.6 UTM 归因规范新增跳转 FastGPT 官网的链接时必须同步登记并复用 document/UTM_ATTRIBUTION.md 中定义的utm_campaign和utm_content核心约定如下域名环境变量FASTGPT_HOME_DOMAIN只配置 origin如https://fastgpt.io或https://fastgpt.cn不能携带路径或查询参数商机来源商机表单的业务来源使用独立的source参数不使用utm_source作为提交来源source由官网 Cookie 保留并写入 CRM 商机UTM 参数仍保留用于匿名渠道分析文档内跳转固定参数utm_sourcedocs、utm_mediumreferral由组件自动附加页面与链接位置使用utm_campaign/utm_content区分。常用的utm_campaign/utm_content组合完整清单见 UTM 归因规范页面utm_campaign链接位置utm_content快速了解 FastGPTdocs_getting_started国际版入口cloud_entry_io快速了解 FastGPTdocs_getting_started中国大陆版入口cloud_entry_cn云服务介绍docs_cloud_intro国际版入口cloud_entry_io云服务介绍docs_cloud_intro中国大陆版入口cloud_entry_cn云服务 FAQdocs_cloud_faq国际版登录帮助login_help_io云服务 FAQdocs_cloud_faq中国大陆版登录帮助login_help_cn本地开发docs_self_host_dev文档开头产品链接intro_product_link本地开发docs_self_host_dev前置环境产品链接prerequisites_product_link文档导航docs_navigation商业咨询入口business_consultation命名规范同一页面或同一推广主题复用同一个utm_campaign用不同utm_content区分具体链接位置新增页面时使用稳定、可读的小写下划线命名不要把文案或时间写入参数。DOCS_UTM_CAMPAIGNS常量在 document/lib/fastgpt-home-url.ts 中也有集中定义可作为类型与取值的双重约束。四、页面注册meta.json 的 pages 字段在书写完 MDX 文档后必须在对应目录的meta.json文件的pages字段合适位置添加自己的文件名否则文档不会出现在导航中。例如在content默认所有文档的根目录下的introduction目录中书写了一个hello.mdx文件则需要去该introduction目录下的meta.json添加{ title: FastGPT Docs, root: true, pages: [[Handshake][联系我们](https://fastgpt.cn/zh/contact?sourcedocsutm_sourcedocsutm_mediumreferralutm_campaigndocs_navigationutm_contentbusiness_consultation), index, guide, development, FAQ, shopping_cart, community, hello], order: 1 }两个要点pages数组的顺序就是最终文档的展示顺序。在上例中hello原本没有添加后hello文档会展示在introduction目录导航的最后pages中的条目可以是纯文件名也可以是 Markdown 格式的外部链接条目如上例中的[Handshake]联系我们用于在导航中插入官网外链。该外链同样遵循 UTM 归因规范携带了utm_campaigndocs_navigation、utm_contentbusiness_consultation等参数。meta.json中的order字段控制该目录在上级导航中的排序位置root: true标记其为根级分组。这里的metaschema 由 Fumadocs 的metaSchema统一校验见 document/source.config.ts。五、i18n 双语维护文档站的国际化遵循默认文件 语言后缀文件的约定content下的所有.mdx文件为默认语言文件当前默认语言为中文.en.mdx文件为英文翻译文件。例如将hello.mdx翻译后写成hello.en.mdx即可同时在对应目录的meta.en.json的pages字段中写下对应的文件名以支持英文导航。i18n 的核心配置在 document/lib/i18n.tsexport const i18n: I18nConfig { defaultLanguage: zh-CN, languages: [zh-CN, en], hideLocale: never };defaultLanguage: zh-CN默认语言为简体中文languages: [zh-CN, en]支持简体中文与英文两种语言hideLocale: neverURL 中始终保留语言前缀如/zh-CN/guide/...、/en/guide/...这也是getLocalizedPathdocument/lib/i18n.ts返回带前缀路径的依据。在此基础上文档站还提供了语言感知的导航工具document/lib/localized-navigation.tsuseCurrentLang()从当前 pathname 的第一个路径段解析语言解析不到时回退到默认语言useLocalizedPath(path)把基础路径转换为带当前语言前缀的路径useLocalizedRouter()包装 Next.jsuseRouter使push/replace/prefetch自动附加语言前缀。因此自定义组件内需要跳转文档内页面时应优先使用这些工具避免硬编码语言前缀。六、特殊配置导航栏与重定向6.1 增加顶层导航栏如需在文档站顶部导航栏新增栏目编辑FastGPT/document/app/[lang]/docs/layout.tsx文件在其中新增导航项即可。该布局文件是所有文档页面的顶层布局[lang]动态段对应 i18n 的语言前缀导航配置变更会作用于中英文两套站点。注意本文所述路径为仓库内 document/app/[lang]/docs/layout.tsx。6.2 兜底重定向404 → 首页对于不存在的页面文档站在 document/components/docs/not-found.tsx 中实现了全局兜底当页面未找到时NotFound组件会通过window.location.replace将用户重定向到defaultHomePath即/guide/getting-started定义于 document/lib/i18n.ts从而避免出现 404 死链。新增重定向规则例如把某个废弃文档指向新文档就在此文件中维护。七、进阶理解文档构建管线除 README 介绍的日常开发流程外从源码可以进一步看到文档站完整的构建管线内容收集fumadocs-mdx通过 document/source.config.ts 中的defineDocs({ dir: content, ... })收集content目录下的全部 MDX 与meta.json并以 Zod 校验 frontmatter基础title/description/icon之外还支持releaseTime、sidebarTag、upgradeTags扩展字段MDX 预处理mdxOptions.remarkPlugins注册了remarkMermaid插件它会遍历 MDX AST把所有lang mermaid的代码块转换为MermaidDiagramJSX 节点从而在文档中直接渲染流程图文档辅助数据仓库内 document/data/doc-last-modified.json 记录文档最后修改时间由initDocTime脚本生成供lastModifiedTime: git之外的时间展示使用script/checkDocRefs.js用于校验文档引用有效性script/removeInvalidImg.js清理失效图片引用——这些是保持文档质量的自检机制搜索支持依赖orama/orama与orama/tokenizers为文档站提供全文检索能力见 document/package.json。结语FastGPT 文档站虽然是一个文档项目但其工程化程度并不亚于主应用基于 Fumadocs 的内容收集管线、可扩展的 frontmatter schema、围绕官网转化打造的 UTM 归因体系、完备的中英双语 i18n 机制以及 Alert / Tabs / Redirect / FastGPTLink 等定制组件共同构成了一个可维护、可检索、可追踪来源的官方技术文档平台。无论是新增一篇普通指南还是调整导航结构、新增重定向、维护多语言都可以在上文的工作流中找到对应操作路径与源码依据。【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
