企业官网建设流程全解析

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 15（fumadocs-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_DOMAIN=https://fastgpt.io # 只填写 origin，不携带路径或查询参数

注意两个关键约束：

1. 只填写 origin（协议 + 域名），不要携带路径或查询参数；
2. 该变量决定文档中FastGPTLink组件生成的官网跳转链接指向哪个站点。

该变量的实际解析逻辑在 document/lib/fastgpt-home-url.ts：getFastGPTHomeOrigin会优先读取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 常用脚本一览

三、书写文档：MDX 格式与 frontmatter

3.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 做了扩展，还支持releaseTime（ISO 日期）、sidebarTag（侧边栏标签）、upgradeTags（升级标签数组）等可选字段，供版本发布与升级时间线等场景使用。也就是说，在书写基础文档时使用title/description/icon即可，涉及版本升级类文档时还可利用releaseTime、upgradeTags增强表现。

3.2 内置组件：Alert 高亮块

Alert用于在文档中插入带图标、带语义色彩的高亮提示块，书写语法为：

import { Alert } from '@/components/docs/Alert'; # 高亮块组件 <Alert icon="🤖" context="success"> 快速开始体验 - 海外版：<FastGPTLink campaign="docs_getting_started" content="cloud_entry_io" site="io">{'https://fastgpt.io'}</FastGPTLink> - 中国大陆：<FastGPTLink campaign="docs_getting_started" content="cloud_entry_cn" site="cn">{'https://fastgpt.cn'}</FastGPTLink> </Alert>

context支持四种语义取值，对应不同的配色方案（见 document/components/docs/Alert.tsx）：

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，核心逻辑有三点：

1. 兼容带语言前缀的路径：removeLocalePrefix会先剥离路径中的语言段（如/zh-CN/...），再执行跳转；
2. 兼容.mdx后缀：normalizeDocPath会去掉.mdx或.en.mdx后缀，支持以源码文件路径形式书写to参数；
3. 自动补语言前缀：跳转目标最终会经过getLocalizedPath加上当前语言前缀，保证中英文环境各自跳到正确版本。

to参数既支持以/开头的绝对路径，也支持相对当前文档的路径（内部会基于当前 pathname 做 URL 归一化）。

3.4 内置组件：Tabs 多标签内容

Tabs/Tab组件用于在同一位置展示多份可切换内容（如不同编程语言的代码示例）：

import { Tabs } from '@/components/docs/Tabs'; # tabs 组件用法 <Tabs items={['Javascript', 'Rust']}> <Tab value="Javascript">Javascript is weird</Tab> <Tab value="Rust">Rust is fast</Tab> </Tabs>

实现上（document/components/docs/Tabs.tsx），Tabs接收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 campaign="docs_self_host_dev" content="intro_product_link">FastGPT</FastGPTLink>。

该组件会根据环境变量和传入的归因参数自动生成带 UTM 参数的官网链接，其核心实现在 document/lib/fastgpt-home-url.ts：

• site属性决定目标域名：'io'固定指向https://fastgpt.io，'cn'固定指向https://fastgpt.cn，默认值'configured'则使用环境变量FASTGPT_HOME_DOMAIN配置的 origin；
• 自动附加 UTM 参数：无论site取何值，都会固定添加utm_source=docs与utm_medium=referral，并拼接调用方传入的utm_campaign与utm_content；
• 组件本身（document/components/docs/linkFastGPT.tsx）是 Client Component，用useMemo缓存 URL 计算结果，并内置了默认蓝色链接样式与 hover 下划线效果，React.memo包裹以避免不必要的重渲染。

为什么必须用 FastGPTLink？因为归因参数是强制附加的，使用裸链接会丢失utm_source=docs与utm_medium=referral，导致官网无法统计文档渠道的流量来源。详见下文 UTM 归因规范。

3.6 UTM 归因规范

新增跳转 FastGPT 官网的链接时，必须同步登记并复用 document/UTM_ATTRIBUTION.md 中定义的utm_campaign和utm_content，核心约定如下：

1. 域名环境变量FASTGPT_HOME_DOMAIN只配置 origin，如https://fastgpt.io或https://fastgpt.cn，不能携带路径或查询参数；
2. 商机来源：商机表单的业务来源使用独立的source参数，不使用utm_source作为提交来源；source由官网 Cookie 保留并写入 CRM 商机，UTM 参数仍保留用于匿名渠道分析；
3. 文档内跳转固定参数：utm_source=docs、utm_medium=referral由组件自动附加，页面与链接位置使用utm_campaign/utm_content区分。

常用的utm_campaign/utm_content组合（完整清单见 UTM 归因规范）：

命名规范：同一页面或同一推广主题复用同一个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?source=docs&utm_source=docs&utm_medium=referral&utm_campaign=docs_navigation&utm_content=business_consultation)", "index", "guide", "development", "FAQ", "shopping_cart", "community", "hello"], "order": 1 }

两个要点：

1. pages数组的顺序就是最终文档的展示顺序。在上例中，"hello"原本没有，添加后hello文档会展示在introduction目录导航的最后；
2. pages中的条目可以是纯文件名，也可以是 Markdown 格式的外部链接条目（如上例中的[Handshake]联系我们，用于在导航中插入官网外链）。该外链同样遵循 UTM 归因规范，携带了utm_campaign=docs_navigation、utm_content=business_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.ts：

export const i18n: I18nConfig = { defaultLanguage: 'zh-CN', languages: ['zh-CN', 'en'], hideLocale: 'never' };

• defaultLanguage: 'zh-CN'：默认语言为简体中文；
• languages: ['zh-CN', 'en']：支持简体中文与英文两种语言；
• hideLocale: 'never'：URL 中始终保留语言前缀（如/zh-CN/guide/...、/en/guide/...），这也是getLocalizedPath（document/lib/i18n.ts）返回带前缀路径的依据。

在此基础上，文档站还提供了语言感知的导航工具（document/lib/localized-navigation.ts）：

• useCurrentLang()：从当前 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 介绍的日常开发流程外，从源码可以进一步看到文档站完整的构建管线：

1. 内容收集：fumadocs-mdx通过 document/source.config.ts 中的defineDocs({ dir: 'content', ... })收集content目录下的全部 MDX 与meta.json，并以 Zod 校验 frontmatter（基础title/description/icon之外，还支持releaseTime、sidebarTag、upgradeTags扩展字段）；
2. MDX 预处理：mdxOptions.remarkPlugins注册了remarkMermaid插件，它会遍历 MDX AST，把所有lang === 'mermaid'的代码块转换为MermaidDiagramJSX 节点，从而在文档中直接渲染流程图；
3. 文档辅助数据：仓库内 document/data/doc-last-modified.json 记录文档最后修改时间（由initDocTime脚本生成），供lastModifiedTime: 'git'之外的时间展示使用；script/checkDocRefs.js用于校验文档引用有效性，script/removeInvalidImg.js清理失效图片引用——这些是保持文档质量的自检机制；
4. 搜索支持：依赖@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