windows下安装并使用gitbook
gitbook的用途
gitbook官网上给出的定位是这样的：
GitBook helps you publish beautiful docs for your users and centralize your teams’ knowledge for advanced collaboration.(翻译过来是这样的：GitBook可以帮助您为用户发布漂亮的文档，并集中团队的知识以实现高级协作)
对于个人来说，使用gitbook无非就是将markdown文档生成html文件，而且提供了一个本地服务器，以便能够在浏览器上进行本地访问(反正我目前就使用了这个功能)。
gitbook的依赖环境
gitbook的安装依赖nodejs的npm包管理功能，而windows没有这样的环境。所以需要在windows平台上安装nodejs。
nodejs的安装
这里建议在nodejs的中文网上下载安装，速度会更快。这里给出了下载nodejs各个版本的网址：
https://npm.taobao.org/mirrors/node/
推荐下载v12.x版本，因为本人亲测可以使用。不建议下载v16.x版本，因为本人亲测版本和gitbook不兼容。至于其他版本是否可行就需要大家亲自实验了。对于每一个版本在windows平台下都有以下几种：
node-v12.20.1-win-x64.7z 04-Jan-2021 12:41 0661888(10.17MB)
node-v12.20.1-win-x64.zip 04-Jan-2021 12:42 18672143(17.81MB)
node-v12.20.1-win-x86.7z 04-Jan-2021 12:20 9579436(9.14MB)
node-v12.20.1-win-x86.zip 04-Jan-2021 12:20 17127042(16.33MB)
node-v12.20.1-x64.msi 04-Jan-2021 12:43 19664896(18.75MB)
node-v12.20.1-x86.msi 04-Jan-2021 12:21 18026496(17.19MB)
下载首先排除x86文件，剩下的.7z和.zip是压缩文件，直接解压就行，无需安装，但是需要自己配置npm的环境变量。msi文件不需要解压，但是需要安装，安装时会默认配置好环境变量。大家根据需要自行选择。
安装成功后，可以在控制台使用node -v查看自己安装是否成功。
PS C:\Users\15949\Desktop\gitbook> node -v
v16.13.1
PS C:\Users\15949\Desktop\gitbook>
gitbook安装
直接使用以下命令可以安装gitbook：
npm install gitbook-cli -g
安装该命令安装后gitbook包会默认放在nodejs安装路径下的node_global文件夹下，所以要想全局使用gitbook命令，还需要将该文件夹设置为环境变量。
设置完环境变量后，可以在控制台使用gitbook -V查看是否安装成功(这里V是大写)。
C:\Users\15949>gitbook -V
CLI version: 2.3.2
Installing GitBook 3.2.3
这里在测试版本的时候也会自动执行gitbook install命令，即有可能出现TypeError: cb.apply is not a function错误
//报错
C:\Users\15949>gitbook -V
CLI version: 2.3.2
Installing GitBook 3.2.3
C:\Users\15949\AppData\Roaming\npm\node_modules\gitbook-cli\node_modules\npm\node_modules\graceful-fs\polyfills.js:287
if (cb) cb.apply(this, arguments)
^
TypeError: cb.apply is not a function
at C:\Users\15949\AppData\Roaming\npm\node_modules\gitbook-cli\node_modules\npm\node_modules\graceful-fs\polyfills.js:287:18
at FSReqCallback.oncomplete (node:fs:199:5)
文末写明解决方案
gitbook使用
新建一个文件夹，例如first-gitbook，在控制台进入到该文件夹下，使用gitbook init进行初始化。在文件夹下会生成两个markdown文档：README和SUMMARY，初始化完成。
然后使用gitbook serve命令，该命令会将文件夹下生成一个_book文件夹，该文件夹下是生成的网站结构，包括gitbook自带的网页排版。同时会启动本地服务器，我们可以使用localhost:4000访问到。
- README文档中的内容就是网站的index主页的内容。
- SUMMARY文档描述了网站的结构。
暂无示例展示
gitbook开启多个服务
如果你想同时编辑两个或多个gitbook，使用gitbook serve命令会报错。这是因为使用gitbook会默认使用电脑的35729端口给4000端口提供服务。使用gitbook serve命令时发现这两个端口被占用而退出。
但是gitbook提供了命令可以修改默认端口。使用如下命令就能达到这样的效果：
gitbook serve --lrport 35728 --port 4001
报错一：gitbook serve报错（与gitbook install报错相同）
在使用gitbook serve命令时可能会出现以下错误：
C:\Users\15949\AppData\Roaming\npm\node_modules\gitbook-cli\node_modules\npm\node_modules\graceful-fs\polyfills.js:287
if (cb) cb.apply(this, arguments)
^
TypeError: cb.apply is not a function
at C:\Users\15949\AppData\Roaming\npm\node_modules\gitbook-cli\node_modules\npm\node_modules\graceful-fs\polyfills.js:287:18
at FSReqCallback.oncomplete (node:fs:199:5)
解决方案一：
我们只需要找到报错所说的polyfills.js文件，打开polyfills.js文件287行，找到这个函数
function statFix (orig) {
if (!orig) return orig
// Older versions of Node erroneously returned signed integers for
// uid + gid.
return function (target, cb) {
return orig.call(fs, target, function (er, stats) {
if (!stats) return cb.apply(this, arguments)
if (stats.uid < 0) stats.uid += 0x100000000
if (stats.gid < 0) stats.gid += 0x100000000
if (cb) cb.apply(this, arguments)
})
}
}
在第62-64行调用了这个函数，只需要注释掉这三行就可以了
//fs.stat = statFix(fs.stat)
//fs.fstat = statFix(fs.fstat)
//fs.lstat = statFix(fs.lstat)
解决方案二：降低node版本
nvm install 10.14.1
nvm use 10.14.1
选择10.21.0版本或者10.14.1或者12.x.x就可以，其中nvm需要另外单独安装，相较于直接使用nodejs更加方便版本控制
**报错二：**Gitbook：无法加载文件C:\Users\Administrator\AppData\Roaming\npm\gitbook.ps1因为在此系统上禁止运行脚本的解决方法
PS C:\Users\15949\Desktop\gitbook> gitbook init
gitbook : 无法加载文件 C:\Users\15949\AppData\Roaming\npm\gitbook.ps1，因为在此系统上禁止运行脚本。有关详细信息，请参阅
https:/go.microsoft.com/fwlink/?LinkID=135170 中的 about_Execution_Policies。
所在位置 行:1 字符: 1
+ gitbook init
+ ~~~~~~~
+ CategoryInfo : SecurityError: (:) []，PSSecurityException
+ FullyQualifiedErrorId : UnauthorizedAccess
PS C:\Users\15949\Desktop\gitbook>
解决方法一：
win11系统：设置—隐私与安全性—-开发者选项
打开“更改执行策略”
并在powershell管理员模式执行set-ExecutionPolicy RemoteSigned（签名或运行这些脚本）
Windows PowerShell
版权所有（C） Microsoft Corporation。保留所有权利。
安装最新的 PowerShell，了解新功能和改进！https://aka.ms/PSWindows
PS C:\WINDOWS\system32> set-ExecutionPolicy RemoteSigned
执行策略更改
执行策略可帮助你防止执行不信任的脚本。更改执行策略可能会产生安全风险，如 https:/go.microsoft.com/fwlink/?LinkID=135170
中的 about_Execution_Policies 帮助主题所述。是否要更改执行策略?
[Y] 是(Y) [A] 全是(A) [N] 否(N) [L] 全否(L) [S] 暂停(S) [?] 帮助 (默认值为“N”): Y
报错三：warn: no summary file in this book
C:\Windows\system32>gitbook init
warn: no summary file in this book
info: create SUMMARY.md
解决方法一：降低node版本
nvm install 10.14.1
nvm use 10.14.1
选择10.21.0版本或者10.14.1或者12.x.x就可以，其中nvm需要另外单独安装，相较于直接使用nodejs更加方便版本控制
「真诚赞赏，手留余香」
Ryen's Blog
真诚赞赏，手留余香
使用微信扫描二维码完成支付
