Gitbook 基本安装

本文介绍 Gitbook 旧版命令行工具（Legacy CLI）的安装前置条件、安装步骤与版本校验方法，并补充当前在新版 Node.js 环境下的兼容性注意事项。Gitbook 的安装本质上是「准备 Node.js 运行时 → 通过 npm 安装 CLI → 校验版本」三步。

前置认知:Legacy CLI 与 GitBook.com 的关系

在动手之前，需要先厘清两个容易混淆的概念:

• GitBook.com:GitBook 公司推出的在线 SaaS 文档平台，目前为闭源商业产品，通过浏览器编辑器直接托管内容。
• Gitbook Legacy CLI(旧版命令行工具):基于 Node.js 的开源工具链，使用 Git 和 Markdown 在本地构建电子书与文档站点，可输出 HTML 静态网站、PDF、EPUB、MOBI。

本文及后续几篇文章讨论的「Gitbook」均指后者——即旧版 CLI。需要特别说明的是，GitBook 官方在仓库 GitbookIO/gitbook 的 legacy 分支 README 中已将旧版 CLI 明确标注为 “Legacy GitBook (Deprecated)”,CLI 工具(GitbookIO/gitbook-cli)亦声明 “the CLI is no longer under active development”(不再积极开发)。其最后一个稳定版本停留在 3.2.x,对较新版本的 Node.js 兼容性较差。

尽管如此，大量历史项目、内网文档和教程仍基于 Legacy CLI，理解它的安装与使用依然有价值。若新项目希望沿用同一套工具链，建议直接使用其活跃 fork HonKit。

Node.js 安装

Node.js 是一个基于 Chrome V8 JavaScript 运行时建立的平台，用来方便地搭建快速的、易于扩展的网络应用。

Node.js 借助事件驱动、非阻塞 I/O 模型变得轻量和高效，非常适合运行在分布式设备上、数据密集型的实时应用。

Gitbook CLI 本身是一个 npm 包，因此第一步是准备 Node.js 运行时。

版本建议

由于 Legacy CLI 依赖的若干原生模块和旧版依赖链，与 Node.js 16 及以上版本存在兼容性问题(Node 17+ 默认禁用了 OpenSSL 旧算法，会触发 ERR_OSSL_EVP_UNSUPPORTED 一类错误)。实务中推荐的版本组合:

截至本文更新时，Node.js 的活跃 LTS 版本为 24.x (Krypton),维护期 LTS 为 22.x (Jod),Current 为 26.x。建议使用 nvm(Unix/macOS)或 nvm-windows、fnm 等版本管理工具在多个 Node 版本之间切换，以兼顾新旧工具链。

安装与校验

Node.js 的安装请参考官方下载页 nodejs.org 或社区教程:

在 Windows、Mac OS X 與 Linux 中安裝 Node.js 網頁應用程式開發環境

安装完成后，通过下面的命令验证 Node.js 及其包管理器 npm 是否就绪:

$ node -v
v12.22.12

$ npm -v
6.14.16

只要两条命令都能正常输出版本号，说明运行环境已经准备好，可以进入下一步。

Gitbook CLI 安装

Gitbook CLI 通过 npm 全局安装。最规范的包名是 gitbook-cli(命令行入口),而不是直接安装 gitbook 核心库——CLI 会在首次运行时按需自动下载并管理对应版本的 gitbook 核心。

$ npm install -g gitbook-cli

原始资料中写作 npm install gitbook -g。这在新版 npm 中可能会因为缺少 -g 位置或包名差异报错，推荐使用 npm install -g gitbook-cli 的写法。

安装完成后，用下面的命令校验:

$ gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

gitbook -V(大写 V)会同时输出 CLI 自身版本和当前使用的 GitBook 核心版本。看到类似输出即代表安装成功;首次执行时 CLI 会从远程拉取默认的 GitBook 核心版本到本地缓存目录 ~/.gitbook,可以通过环境变量 GITBOOK_DIR 修改该缓存路径。

常用命令速览

安装完成后，以下命令构成了 Gitbook 的日常工作流(完整列表可执行 gitbook -h 查看):

需要注意的是，CLI 只管理 >= 2.0.0 的 GitBook 版本。

通过 book.json 声明插件

Gitbook 的扩展能力依赖插件机制。在书籍根目录创建 book.json,声明所需插件后再执行 gitbook install,CLI 会读取配置并自动从 npm 拉取对应的 gitbook-plugin-* 包:

{
  "plugins": [
    "search",
    "sharing",
    "fontsettings",
    "theme-default",
    "copy-code-button",
    "alerts"
  ],
  "pluginsConfig": {
    "theme-default": {
      "showLevel": true
    }
  }
}

插件命名遵循 gitbook-plugin-<name> 约定，在 plugins 数组里只需写 <name> 部分。也可以直接用 npm 安装:npm install gitbook-plugin-copy-code-button --save。

常见问题

安装或运行时报 cb.apply is not a function 通常是 Node.js 版本过新导致的依赖不兼容，降到 Node 10–12 即可解决。

构建时出现 ERR_OSSL_EVP_UNSUPPORTED 是 Node 17+ 默认禁用了旧 OpenSSL 算法，临时方案是设置环境变量:

export NODE_OPTIONS=--openssl-legacy-provider

gitbook install 卡住或失败 多见于网络问题或 npm registry 不可达，可尝试切换镜像源(npm config set registry https://registry.npmmirror.com)。

现代替代方案

由于 Legacy CLI 已经停止维护，且与新版 Node.js 兼容性持续恶化，新项目建议考虑以下工具:

• HonKit:Legacy GitBook 的活跃 fork,TypeScript 重写，兼容绝大多数 gitbook-plugin-* 插件，迁移成本最低，要求 Node.js 14+。
• mdBook:Rust 实现，零运行时依赖，构建极快。
• Docusaurus:React 驱动，适合大型产品文档站。
• VitePress / VuePress:Vue 生态，配置简单，主题丰富。

选择时主要看团队技术栈、对旧 GitBook 插件的依赖程度以及输出格式需求。

小结

• Gitbook Legacy CLI 的安装分两步：先准备 Node.js 运行时（推荐 10.x / 12.x）,再执行 npm install -g gitbook-cli。
• 用 gitbook -V 同时校验 CLI 与核心版本;日常命令围绕 init / install / serve / build 展开。
• 由于官方已将该工具链标记为 Deprecated，新项目应优先考虑 HonKit 或 mdBook 等现代替代方案。

参考

• GitbookIO/gitbook — GitHub(Legacy Deprecated 分支)
• GitbookIO/gitbook-cli — GitHub
• HonKit — GitBook Legacy 的活跃 fork
• Node.js Release Schedule
• nvm — Node Version Manager