GitBook 完整使用指南：从安装到部署

文章目录

环境准备Node.js 安装GitBook CLI 安装
项目初始化创建项目结构(可选) npm 初始化
目录结构配置开发与调试本地服务启动构建静态文件
配置文件详解插件系统常用插件推荐插件安装与配置
自定义样式部署指南GitHub Pages 部署Netlify 部署
高级功能多语言支持电子书导出
故障排除常见问题解决
GitBook 替代方案结语

环境准备

Node.js 安装

由于 GitBook 已停止更新，建议使用 Node.js v10.x 版本以避免兼容性问题：

# 使用 nvm 安装和管理 Node.js 版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 10.22.0
nvm use 10.22.0

GitBook CLI 安装

npm install -g gitbook-cli
gitbook -V  # 验证安装

项目初始化

创建项目结构

# 创建项目目录
mkdir my-documentation && cd my-documentation

# 初始化 GitBook
gitbook init

初始化后会生成两个核心文件：


README.md – 书籍简介
SUMMARY.md – 目录结构定义

(可选) npm 初始化

npm init -y

在
package.json 中添加脚本：

{
  "scripts": {
    "serve": "gitbook serve",
    "build": "gitbook build",
    "install": "gitbook install"
  }
}

目录结构配置

编辑
SUMMARY.md 文件来定义你的书籍结构：

# 目录概览

* [简介](README.md)
* [第一部分: 基础概念](part1/README.md)
  * [1.1 写作指南](part1/writing.md)
  * [1.2 GitBook 功能](part1/gitbook.md)
* [第二部分: 高级功能](part2/README.md)
  * [2.1 反馈机制](part2/feedback_please.md)
  * [2.2 工具集成](part2/better_tools.md)
* [附录](appendix/README.md)

确保创建相应的目录和 Markdown 文件。

开发与调试

本地服务启动

# 直接使用 GitBook 命令
gitbook serve

# 或使用 npm 脚本
npm run serve

服务启动后，访问
http://localhost:4000 查看实时预览。

构建静态文件

gitbook build
# 或
npm run build

构建完成后，静态文件将生成在
_book 目录中。

配置文件详解

创建
book.json 来自定义你的 GitBook：

{
  "title": "你的文档标题",
  "author": "你的名字",
  "description": "项目详细文档说明",
  "language": "zh-cn",
  "gitbook": "3.2.3",
  "styles": {
    "website": "styles/website.css"
  },
  "structure": {
    "readme": "README.md",
    "summary": "SUMMARY.md"
  },
  "plugins": [
    "search-pro",
    "code",
    "expandable-chapters",
    "back-to-top-button"
  ],
  "pluginsConfig": {
    "fontsettings": {
      "theme": "white",
      "family": "sans",
      "size": 2
    },
    "code": {
      "copyButtons": true
    }
  }
}

插件系统

常用插件推荐

插件名称	功能描述	安装命令
search-pro	增强搜索功能，支持中文	npm install gitbook-plugin-search-pro
code	代码块行号和复制按钮	npm install gitbook-plugin-code
expandable-chapters	可折叠侧边栏章节	npm install gitbook-plugin-expandable-chapters
back-to-top-button	返回顶部按钮	npm install gitbook-plugin-back-to-top-button
theme-comscore	现代化主题	npm install gitbook-plugin-theme-comscore

插件安装与配置

在
book.json 的
plugins 数组中添加插件运行安装命令：

gitbook install
# 或
npm run install

自定义样式

创建
styles/website.css 文件来自定义样式：

/* 修改主题颜色 */
.book .book-summary {
  background-color: #f5f5f5;
}

/* 调整代码块样式 */
pre {
  border-radius: 5px;
  border: 1px solid #eaeaea;
}

/* 自定义字体 */
body {
  font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
}

部署指南

GitHub Pages 部署

构建项目：

npm run build

将
_book 目录内容推送到
gh-pages 分支：

git subtree push --prefix _book origin gh-pages

Netlify 部署

连接你的 Git 仓库到 Netlify设置构建命令：
gitbook build设置发布目录：
_book部署！

高级功能

多语言支持

{
  "language": "zh-cn",
  "plugins": ["livereload", "highlight", "search", "lunr", "sharing", "fontsettings", "theme-default"],
  "pluginsConfig": {
    "theme-default": {
      "styles": {
        "website": "styles/website.css"
      }
    }
  }
}

电子书导出

# 安装 Calibre 用于电子书转换
sudo -v && wget -nv -O- https://download.calibre-ebook.com/linux-installer.sh | sudo sh /dev/stdin

# 导出为 PDF
gitbook pdf . my-book.pdf

# 导出为 ePub
gitbook epub . my-book.epub

# 导出为 Mobi
gitbook mobi . my-book.mobi

故障排除

常见问题解决

Node.js 版本问题：

# 如果遇到 cb.apply is not a function 错误
nvm use 10.22.0

端口占用：

gitbook serve --port 4001

插件安装失败：

# 清除缓存重试
npm cache clean --force
gitbook install

GitBook 替代方案

虽然 GitBook 仍然可用，但也可以考虑以下现代替代品：

VuePress – Vue.js 驱动的静态网站生成器Docusaurus – Facebook 开发的文档网站工具Docsify – 动态文档网站生成器MkDocs – Python 开发的文档工具

结语

GitBook 作为一个成熟的文档工具，虽然已经停止官方维护，但其简单易用的特性仍然使其成为许多项目的优秀选择。通过本文的指南，你应该能够快速上手并充分利用 GitBook 来创建专业的技术文档。

记住，好的文档是项目成功的关键因素之一。花时间打造完善的文档，将为你的项目和团队带来长远的价值。