GitBook 入门指南

什么是GitBook

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

核心特性

Markdown 优先
用简洁的 Markdown 语法编写内容，无需复杂排版，专注于文字创作。支持标题层级、列表、代码块、图片、表格等常见格式，同时可通过插件扩展功能（如数学公式、流程图）。
版本控制集成
基于 Git 进行版本管理，可追踪文档的每一次修改（提交历史、作者、时间），支持分支（多人并行编辑）、合并（整合内容）、回滚（恢复旧版本）等 Git 特性，适合团队协作。
结构化目录
通过 SUMMARY.md 文件定义文档结构（类似书籍目录），自动生成章节导航，让内容层次清晰。例如：

# 目录
- [前言](README.md)
- [第一章：基础](chapter1/basic.md)
- [第二章：进阶](chapter2/advanced.md)

多平台发布
1. 在线访问：同步到 GitBook 官网后生成可分享的网页链接（如 https://xxx.gitbook.io/xxx）。
2. 静态部署：生成 HTML 静态文件，部署到 GitHub Pages、服务器等。
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管理工具

验证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 命令行工具）：

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

验证安装

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），进入该文件夹：

mkdir D:\Learn
cd D:\Learn

初始化 GitBook 项目：

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：文档目录结构（定义章节关系，必填）。

插件安装

Gitbook有一个配置文件book.json，在该配置文件中可以配置各种插件，来美化页面的显示和交互效果。由于用到的插件比较多，这里我把常用配置和插件已经写好了，直接粘贴即可。注意：book.json一定要放在根目录下。

{
    "title": "gitbook",
    "author": "mi",
    "output.name": "site",
    "language": "zh-hans",
    "gitbook": "3.2.3",
    "root": ".",
    "plugins": [
        "-sharing",
        "-lunr","-search","search-pro",
        "-highlight","prism@^2.1.0","prism-themes",
        "-default-theme","theme-comscore",
        "splitter",
        "tbfed-pagefooter",
        "expandable-chapters",
        "hide-element",
        "favicon",
        "code",
        "sectionx",
        "flexible-alerts",
        "ancre-navigation",
        "donate@^1.0.2",
        "pageview-count",
        "lightbox",
        "auto-scroll-table"
    ],

    "pluginsConfig": {
        "tbfed-pagefooter": {
            "copyright":"Copyright &copy www.sqlfans.cn 2021",
            "modify_label": "更新时间：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        },

        "hide-element": {
            "elements": [".gitbook-link"]
        },

        "favicon": {
            "shortcut": "icon/home.ico",
            "bookmark": "icon/home.ico"
        },

        "pdf": {
            "pageNumbers": true,
            "fontFamily": "Arial",
            "fontSize": 12,
            "paperSize": "a4",
            "margin": {
                "right": 62,
                "left": 62,
                "top": 56,
                "bottom": 56
            }
        },

       "prism":{
            "css":[
                "prism-themes/themes/prism-darcula.css"
            ]
       },

       "sectionx": {
          "tag": "b"
        },

        "donate": {
            "wechat": "https://static.sqlfans.cn/image/QRcode/weixin.jpg",
            "alipay": "https://static.sqlfans.cn/image/QRcode/alipay.jpg",
            "title": "",
            "button": "赏",
            "alipayText": "支付宝打赏",
            "wechatText": "微信打赏"
        }
    },

    "styles": {
        "website": "styles/website.css",
        "ebook": "styles/ebook.css",
        "pdf": "styles/pdf.css",
        "mobi": "styles/mobi.css",
        "epub": "styles/epub.css"
    }
}

写好配置文件之后，需要执行命令来安装插件（这里下载插件需要一点时间，耐心等待即可）

cd D:\learn

gitbook install

注：book.json 一定要以UTF-8格式保存，否则有些插件会显示乱码，

编写文档内容

编辑目录（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）。
本地预览文档

启动本地服务预览：

# 启动服务
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，打开浏览器访问该地址即可实时查看文档效果（修改内容后浏览器会自动刷新）。

生成静态文件（发布用）

构建静态网页：

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

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

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”）。

总结

Windows 10 下使用 GitBook 的核心是「通过 NVM 切换到 Node 10.x」，否则会出现各种兼容性问题。按照上述步骤，你可以快速搭建文档项目，编写内容并预览，最后生成静态文件或电子书发布。

posted on 2025-08-24 20:33 窥视未来阅读(78) 评论(0) 收藏举报

刷新页面返回顶部

窥视未来

GitBook 入门指南

GitBook 入门指南

核心特性

一、环境准备（必做）

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

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

二、GitBook 命令行工具

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

1. 初始化文档项目

插件安装

编写文档内容

本地预览文档

生成静态文件（发布用）

四、常见问题解决

总结

导航

公告