GitBook 入门指南

什么是GitBook

GitBook 是一个基于 Git 和 Markdown 的的文档协作与发布平台，最初设计用于创建技术书籍、API 文档、知识库等结构化内容，核心特点是将「版本控制」与「文档编写」深度结合，方便团队协作和内容管理。

核心特性

Markdown 优先

用简洁的 Markdown 语法编写内容，无需复杂排版，专注于文字创作。支持标题层级、列表、代码块、图片、表格等常见格式，同时可通过插件扩展功能（如数学公式、流程图）。
版本控制集成

基于 Git 进行版本管理，可追踪文档的每一次修改（提交历史、作者、时间），支持分支（多人并行编辑）、合并（整合内容）、回滚（恢复旧版本）等 Git 特性，适合团队协作。
结构化目录

通过 SUMMARY.md 文件定义文档结构（类似书籍目录），自动生成章节导航，让内容层次清晰。例如：

md 复制代码

`# 目录`

`- [前言](README.md)`

`- [第一章：基础](chapter1``/basic``.md)`

`- [第二章：进阶](chapter2``/advanced``.md)`

多平台发布

1.1、在线访问：同步到 GitBook 官网后生成可分享的网页链接（如 https://xxx.gitbook.io/xxx）。 1.2、静态部署：生成 HTML 静态文件，部署到 GitHub Pages、服务器等。 1.3、离线格式：导出为 PDF、EPUB 等电子书格式。
协作功能

支持多人通过 Git 仓库（GitHub/Gitee）共同编辑，通过 Pull Request 审核内容，适合团队维护技术文档或开源项目手册。

在 Windows 10 环境下安装和使用 GitBook 主要分为「环境准备」「安装 GitBook」「创建文档」三个步骤，以下是详细教程：

一、环境准备（必做）

GitBook 依赖 Node.js 运行，但对高版本 Node 兼容性较差，需通过 NVM 管理低版本 Node.js（推荐 Node 10.x）。

1. 安装 NVM（Node 版本管理器）

下载 NVM 安装包：访问 nvm-windows Releases，下载 nvm-setup.exe（最新版即可）。
安装 NVM：双击安装包，按提示完成安装（默认路径即可，注意不要有中文或空格）。
验证 NVM：打开新的命令提示符（CMD）或 PowerShell，输入 nvm version，若显示版本号则安装成功。

2. 安装 Node.js 10.x（兼容 GitBook 的版本）

安装 Node 10：在终端执行'

本机已实现安装 NVM node管理工具

3. 验证Node版本

(base) PS D:\Learn> node -``v

v10.24.1

(base) PS D:\Learn> npm -``v

6.14.12

v10.x 是经过验证的唯一兼容版本，其他版本（v12+）必然会出现各种依赖错误。

二、GitBook 命令行工具

全局安装 gitbook-cli（GitBook 命令行工具）：

shell 复制代码

`npm ``install` `-g gitbook-cli`

 

 

`# 重新安装（指定兼容版本）`

`npm ``install` `-g gitbook-cli@2.3.2 --unsafe-perm`

 

`npm warn deprecated q@1.5.0: You or someone you depend on is using Q, the JavaScript Promise library that gave JavaScript developers strong feelings about promises. They can almost certainly migrate to the native JavaScript promise now. Thank you literally everyone ``for` `joining me ``in` `this bet against the odds. Be excellent to each other.`

`npm warn deprecated`

`npm warn deprecated (For a CapTP with native promises, see @endo``/eventual-send` `and @endo``/captp``)`

 

`added 21 packages ``in` `29s`

`npm notice`

`npm notice New major version of npm available! 10.8.2 -> 11.5.2`

`npm notice Changelog: https:``//github``.com``/npm/cli/releases/tag/v11``.5.2`

`npm notice To update run: npm ``install` `-g npm@11.5.2`

`npm notice`

验证安装

shell 复制代码

`gitbook -V  ``# 注意是大写 V，首次运行会自动安装 GitBook 核心依赖`

 

 

`CLI version: 2.3.2`

`Installing GitBook 3.2.3`

`gitbook@3.2.3 C:\Users\MI\AppData\Local\Temp\tmp-18768NPuAYcuNvOEI\node_modules\gitbook`

`├── escape-html@1.0.3`

`├── escape-string-regexp@1.0.5`

`├── destroy@1.0.4`

`├── ignore@3.1.2`

`├── ``bash``-color@0.0.4`

`├── gitbook-plugin-livereload@0.0.1`

`├── graceful-fs@4.1.4`

`├── nunjucks-``do``@1.0.0`

`├── ``cp``@0.2.0`

`├── github-slugid@1.0.1`

`├── q@1.4.1`

`├── gitbook-plugin-fontsettings@2.0.0`

`├── spawn-cmd@0.0.2`

`├── is@3.3.2`

`├── ``open``@0.0.5`

`├── direction@0.1.5`

`├── object-path@0.9.2`

`├── extend@3.0.2`

`├── json-schema-defaults@0.1.1`

`├── gitbook-plugin-search@2.2.1`

`├── jsonschema@1.1.0`

`├── crc@3.4.0`

`├── urijs@1.18.0`

`├── semver@5.1.0`

`├── immutable@3.8.2`

`├── front-matter@2.3.0`

`├── error@7.0.2 (string-template@0.2.1, xtend@4.0.2)`

`├── dom-serializer@0.1.0 (domelementtype@1.1.3, entities@1.1.2)`

`├── npmi@2.0.1 (semver@4.3.6)`

`├── tmp@0.0.28 (os-tmpdir@1.0.2)`

`├── mkdirp@0.5.1 (minimist@0.0.8)`

`├── omit-keys@0.1.0 (isobject@0.2.0, array-difference@0.0.1)`

`├── resolve@1.1.7`

`├── send@0.13.2 (etag@1.7.0, statuses@1.2.1, fresh@0.3.0, range-parser@1.0.3, ms@0.7.1, depd@1.1.2, debug@2.2.0, mime@1.3.4, http-errors@1.3.1, on-finished@2.3.0)`

`├── fresh-require@1.0.3 (is-require@0.0.1, shallow-copy@0.0.1, sleuth@0.1.1, astw@1.3.0, through2@0.6.5, escodegen@1.14.3, acorn@0.9.0)`

`├── gitbook-plugin-theme-default@1.0.7`

`├── ``rmdir``@1.2.0 (node.flow@1.2.3)`

`├── js-yaml@3.14.1 (esprima@4.0.1, argparse@1.0.10)`

`├── tiny-lr@0.2.1 (parseurl@1.3.3, livereload-js@2.4.0, qs@5.1.0, debug@2.2.0, body-parser@1.14.2, faye-websocket@0.10.0)`

`├── cpr@1.1.1 (rimraf@2.4.5)`

`├── gitbook-plugin-lunr@1.2.0 (html-entities@1.2.0, lunr@0.5.12)`

`├── chokidar@1.5.0 (async-each@1.0.6, path-is-absolute@1.0.1, inherits@2.0.4, glob-parent@2.0.0, is-binary-path@1.0.1, is-glob@2.0.1, anymatch@1.3.2, readdirp@2.2.1)`

`├── nunjucks@2.5.2 (asap@2.0.6, yargs@3.32.0, chokidar@1.7.0)`

`├── gitbook-plugin-highlight@2.0.2 (highlight.js@9.2.0)`

`├── moment@2.13.0`

`├── ``read``-installed@4.0.3 (debuglog@1.0.1, util-extend@1.0.3, slide@1.1.6, readdir-scoped-modules@1.1.0, ``read``-package-json@2.1.2)`

`├── gitbook-plugin-sharing@1.0.2 (lodash@3.10.1)`

`├── cheerio@0.20.0 (entities@1.1.2, css-``select``@1.2.0, htmlparser2@3.8.3, jsdom@7.2.2, lodash@4.17.21)`

`├── i18n-t@1.0.1 (lodash@4.17.21)`

`├── gitbook-asciidoc@1.2.2 (gitbook-html@1.3.3, asciidoctor.js@1.5.5-1, lodash@4.17.21)`

`├── gitbook-markdown@1.3.2 (kramed-text-renderer@0.2.1, gitbook-html@1.3.3, kramed@0.5.6, lodash@4.17.21)`

`├── request@2.72.0 (oauth-sign@0.8.2, aws-sign2@0.6.0, tunnel-agent@0.4.3, forever-agent@0.6.1, is-typedarray@1.0.0, aws4@1.13.2, caseless@0.11.0, stringstream@0.0.6, isstream@0.1.2, json-stringify-safe@5.0.1, tough-cookie@2.2.2, qs@6.1.2, node-uuid@1.4.8, mime-types@2.1.35, combined-stream@1.0.8, bl@1.1.2, hawk@3.1.3, har-validator@2.0.6, http-signature@1.1.1, form-data@1.0.1)`

`├── juice@2.0.0 (deep-extend@0.4.2, slick@1.12.2, batch@0.5.3, cssom@0.3.1, commander@2.9.0, cross-spawn-async@2.2.5, web-resource-inliner@2.0.0)`

`└── npm@3.9.2`

`GitBook version: 3.2.3`

`(base) PS D:\Learn>`

若输出类似 CLI version: 2.3.2 则安装成功。

三、使用 GitBook 创建和管理文档

1. 初始化文档项目

新建一个文件夹（如 D:\Learn），进入该文件夹：

shell 复制代码

`mkdir` `D:\Learn`

`cd` `D:\Learn`

初始化 GitBook 项目：

shell 复制代码

`gitbook init`

 

`warn: no summary ``file` `in` `this book`

`info: create README.md`

`info: create SUMMARY.md`

 

`TypeError [ERR_INVALID_ARG_TYPE]: The ``"data"` `argument must be of ``type` `string or an instance of Buffer, TypedArray, or DataView. Received an instance of Promise`

此处可能会出现上述的错误，我搜索到的解决方法是需要降低Node版本。

执行后会生成两个文件：
- README.md：文档首页内容（必填）。
- SUMMARY.md：文档目录结构（定义章节关系，必填）。

编写文档内容

编辑目录（SUMMARY.md） ：用记事本或 Markdown 编辑器（如 Typora、VS Code）打开 SUMMARY.md，按以下格式定义章节： # 目录

- [前言](README.md)

- [第一章：Git 基础](chapter1``/git-basic``.md)

- [第二章：GitBook 使用](chapter2``/gitbook-guide``.md)

保存后，执行 gitbook init 会自动创建 chapter1、chapter2 文件夹及对应的 .md 文件。
编写章节内容 ：在生成的 .md 文件中用 Markdown 语法编写内容（如 chapter1/git-basic.md）。

本地预览文档

启动本地服务预览：

shell 复制代码

`# 启动服务`

`gitbook serve`

 

`Live reload server started on port: 35729`

`Press CTRL+C to quit ...`

 

`info: 7 plugins are installed`

`info: loading plugin ``"livereload"``... OK`

`info: loading plugin ``"highlight"``... OK`

`info: loading plugin ``"search"``... OK`

`info: loading plugin ``"lunr"``... OK`

`info: loading plugin ``"sharing"``... OK`

`info: loading plugin ``"fontsettings"``... OK`

`info: loading plugin ``"theme-default"``... OK`

`info: found 1 pages`

`info: found 6796 asset files`

`info: >> generation finished with success ``in` `20.5s !`

 

`Starting server ...`

`Serving book on http:``//localhost``:4000`

访问预览页面：终端会提示 Serving book on http://localhost:4000，打开浏览器访问该地址即可实时查看文档效果（修改内容后浏览器会自动刷新）。

生成静态文件（发布用）

构建静态网页：

shell 复制代码

`# 执行此命令后会生成名称为_book的文件夹，里面包含gitbook的静态网页所有的内容`

`gitbook build`

执行后会生成 _book 文件夹，包含所有静态 HTML 文件，可直接部署到服务器或 GitHub Pages 等平台。
生成 PDF 电子书（可选）：需先安装 Calibre 电子书工具，然后执行：

shell 复制代码

`gitbook pdf ./ .``/learn``.pdf`

生成的 mybook.pdf 会保存在当前目录。

四、常见问题解决

"gitbook 不是内部或外部命令" ：
- 检查 Node 版本是否为 10.x（node -v）。
- 重新安装 gitbook-cli 并重启终端。
启动 gitbook serve 时报错（如 Cannot find module 'q'） ：
- 原因：Node 版本过高或依赖未安装完整。
- 解决：确保用 Node 10.x，删除项目目录下的 node_modules 和 _book 文件夹，重新执行 gitbook install 再启动。
生成 PDF 失败：
- 确保 Calibre 已安装并添加到系统环境变量（安装时勾选 "Add to PATH"）。