gitbook初次安装与基本使用【踩坑总结】

最新推荐文章于 2025-04-26 09:07:08 发布

芊

最新推荐文章于 2025-04-26 09:07:08 发布

阅读量1.6k

点赞数 1

分类专栏：工具使用文章标签：经验分享编辑器 windows

本文链接：https://blog.youkuaiyun.com/weixin_43778378/article/details/113678085

版权

工具使用专栏收录该内容

1 篇文章

订阅专栏

本文档详细介绍了在Windows10环境下配置和使用Gitbook来创建电子书的过程，包括安装node.js和npm，安装并初始化Gitbook项目，设置npm源，本地启动和构建静态网页，以及查看目录结构。特别提到了遇到的node.js版本问题及其解决方案。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

环境准备

操作系统：Windows 10 x64
node.js版本：v12.20.1
npm版本：6.14.10

node.js的安装

到官网上选择符合自己需要的版本，下载安装即可。笔者一开始下载的是14.15.4LTS，但后面初始化gitbook时遇到了问题，卸载后重装v12.20.1后方可正常使用。

node.js的卸载

双击安装时所用的msi（例子：node-v14.15.4-x64.msi），点击Next后会看到以下界面：
在这里插入图片描述点击Remove，按照提示即可卸载完毕。

查看node.js版本

# cmd
C:\Windows\system32>node -v
v14.15.4 # 当前安装的node.js版本

安装npm

# cmd
./configure
make
make install
# 查看npm版本信息
npm -v
6.14.10 # 回显正常说明安装成功

gitbook安装

gitbook命令行工具安装

# cmd
npm install -g gitbook-cli

安装过程大概需要几分钟。
查看gitbook是否成功安装。

# cmd
gitbook -V
# 如果出现以下内容，说明已成功安装；如果只有第一行，第二行显示正在安装，参考npm换源。
CLI version: 2.3.2
GitBook version: 3.2.3

npm换源

如果在执行gitbook -V 或 gitbook init 命令时，均会显示：Installing GitBook 3.2.3 .......，且较长一段时间没有任何提示或结果，是因为npm默认使用的国外镜像速度较慢，则可考虑先进行换源，再重新安装：

# cmd
npm config set registry=http://registry.npm.taobao.org -g
gitbook -V

gitbook基本使用

初始化gitbook项目

初始化项目，按照 gitbook 规范会在当前目录自动创建 README.md 和 SUMMARY.md 两个文件。其中，SUMMARY.md 是电子书的章节目录，gitbook 会初始化相应的文件目录结构，所以主要用于开发初始阶段。

# cmd
gitbook init

如果遇到如下报错信息：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

C:\Windows\system32>gitbook init
warn: no summary file in this book
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.js版本问题造成的。参考前文将node.js换成v12.20.1即可解决。

E:\gitbooks>gitbook init
warn: no summary file in this book
info: create SUMMARY.md
info: initialization is finished #出现这条信息说明初始化完成

在本地启动gitbook项目

启动本地服务gitbook serve，默认访问 http://localhost:4000 实时预览。
能够实时预览电子书效果，且大多数开发环境搭建在本地而不是远程服务器中，主要用于开发调试阶段。

E:\gitbooks>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 0 asset files
info: >> generation finished with success in 0.4s !

Starting server ...
Serving book on http://localhost:4000

初始效果如下：
在这里插入图片描述

构建gitbook静态网页

使用gitbook build命令构建静态网页而不启动本地服务器，默认生成文件存放在 _book/ 目录。
输出静态网页后可打包上传到服务器，也可以上传到 github 等网站进行托管，因而主要用于发布准备阶段。

E:\gitbooks>gitbook build
info: 7 plugins are installed
info: 6 explicitly listed
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 0 asset files
info: >> generation finished with success in 0.4s !

查看gitbook目录

E:\gitbooks>tree
.
├─gitbook-demo
└─_book
    └─gitbook
        ├─fonts
        │  └─fontawesome
        ├─gitbook-plugin-fontsettings
        ├─gitbook-plugin-highlight
        ├─gitbook-plugin-lunr
        ├─gitbook-plugin-search
        ├─gitbook-plugin-sharing
        └─images