GitBook 开源文档平台前端本地搭建指南：新手三步跑通

GitBook 开源文档平台前端本地搭建指南：新手三步跑通

【免费下载链接】gitbookThe open source frontend for GitBook doc sites项目地址: https://gitcode.com/gh_mirrors/gi/gitbook

GitBook 是 GitBook 文档平台的开源前端渲染引擎，基于 Next.js 构建，可把任意已发布的文档站点渲染到你自己的本地浏览器中。它适合想自建开源知识库文档站、或想参与文档渲染引擎贡献的开发者。

项目概览：GitBook 文档平台前端能做什么

• 它是什么：一套用 TypeScript + Next.js 编写的渲染层代码，负责把 GitBook 上已发布的文档内容（页面、代码块、API 文档、图表、公式等）渲染成网页。
• 适合谁：想本地预览和改造文档站点外观的开发者，以及希望向文档平台生态提交功能、翻译的社区贡献者。
• 核心亮点：monorepo 结构，主应用位于packages/gitbook/，周边能力拆分为多个可独立发布的包，如packages/expr/（表达式）、packages/react-openapi/（API 文档渲染）、packages/fonts/（字体）。
• 本地渲染任意已发布站点：只要把已发布 GitBook 站点的 URL 拼到本地服务后面，就能在本地看到完整页面，代码改动即时生效。

环境准备清单：确认 Node.js 与 Bun 版本

工具	最低版本	安装指引
Node.js	≥ 22.3	安装 LTS 版即可，项目根目录带.nvmrc（内容为v22.3），装好 nvm 后运行nvm use可自动切到匹配版本
Bun	≥ 1.2.15	官方提供的 curl / PowerShell 一行安装脚本执行即可；低于 1.2.15 不支持项目的文本版 lockfile

两者装好后，建议先node -v和bun -v确认版本达标，再进入下一步。

三步快速上手：从克隆到本地启动

第 1 步：克隆源码

git clone https://gitcode.com/gh_mirrors/gi/gitbook cd gitbook

⚠️ 注意：如果你会把代码对外分发，请保持源码仓库公开以符合 GNU GPLv3；放到私有仓库则需商业许可。

第 2 步：对齐 Node 版本并安装依赖

nvm use bun install

nvm use会读取项目根目录的.nvmrc切到 22.3；bun install按 lockfile 一次性装齐所有工作区依赖。

第 3 步：启动本地开发服务器

bun dev

该命令通过 turbo 并发启动各工作区，首次编译 Next.js 页面需要等几十秒，看到编译完成即表示服务就绪。

运行预览与常用维护命令：本地预览方法

• 预览地址：在http://localhost:3000/url/后面拼上任意已发布 GitBook 站点的路径，例如http://localhost:3000/url/gitbook.com/docs，即可在本地看到该文档站的完整页面、侧边目录与搜索功能。
• 热更新：修改代码保存后刷新浏览器即可看到变化，无需重启服务。

日常维护命令（均在项目根目录执行）：

命令	作用
bun run format	用 oxfmt 统一格式化代码
bun run lint	用 oxlint 做静态检查，bun run lint:fix可自动修复
bun run typecheck	对所有工作区做 TypeScript 类型检查

所有提交的 Pull Request 还会经过视觉对比与性能测试，防止渲染回归。

许可说明与下一步

本项目按GNU GPLv3许可发布：你可以自由使用、修改，但若要分发代码，必须同样公开源码；私有化部署或闭源分发需获取商业许可。另外官方提醒：自行托管渲染层意味着你要自己负责站点可靠性与后续升级跟进。

💡 接下来你可以：修改packages/gitbook/src/components/下的组件尝试改变文档站外观，或在packages/gitbook/src/intl/translations/目录为界面补一份你熟悉语言的翻译，提交你的第一个 Pull Request，一起把这个开源文档平台做得更好。

【免费下载链接】gitbookThe open source frontend for GitBook doc sites项目地址: https://gitcode.com/gh_mirrors/gi/gitbook