Tips:任何技术文章都有时效性,《从0到1手动打造移动广告归因系统》系列会尽力提供技术背景和环境,还请参考前务必看清文章发布时间,以免产生误导
量U移动归因的技术文档采用 gitbook 工具写成,这篇文章将介绍如何在 CentOS、Windows 和 macOS下安装 gitbook 这款写书工具
CentOS
macOS
Windows
CentOS 下安装
CentOS 8.2 及以上
截止当前(2021年5月份),CentOS 7.9 之前版本的官方源均已失效,意味着无法再使用 yum 命令进行在线软件安装,从而对 gitbook 的安装过程造成一些障碍。故这里使用CentOS 8.2做演示,理论上 CentOS 7.9 也可用,但需要自行验证
安装 nodejs
目前 nodejs官网下载 LTS版本为14.16.1,内置的npm包管理器版本为 6.14.12
如果你的CPU是 intel x86_64 位架构,选择 Linux Binaries (x64) 进行下载,如果系统为32位,那么很可能会安装失败
如果你的CPU是 ARM 架构,选择 Linux Binaries (ARM) 对应的版本进行下载
官网下载.png
将下载文件移动到 root 目录下,然后右键点击解开压缩包到当前目录,当然不一定要在 root 目录下进行,可以根据需要更改。如果你不是 root 用户,那就移动到 /home/{登录名} 的家目录下,然后进入到解开的 node-v14.16.1-linux-x64/bin 目录,并在这个 bin 目录下打开 shell 窗口
下载nodejs.png
安装文件准备就绪,设置软链接进行安装
//root用户
ln -s /root/node-v14.16.1-linux-x64/bin/node /usr/bin/node
ln -s /root/node-v14.16.1-linux-x64/bin/npm /usr/bin/npm
//非root用户
ln -s /home/登录名/node-v14.16.1-linux-x64/bin/node /usr/bin/node
ln -s /home/登录名/node-v14.16.1-linux-x64/bin/npm /usr/bin/npm
这里的安装其实就是在 /usr/bin 下设置了两条软链接指向下载好的nodejs安装文件,因为 /usr/bin 目录已经是系统默认环境变量的二进制执行目录,所以不需要再额外修改环境变量就可以直接在shell窗口中执行 node 和 npm 命令
安装nodejs.png
开始安装 gitbook-cli
npm install -g gitbook-cli // -g 为全局安装选项
安装完成后可以看到当前目录下多了一个gitbook文件
安装gitbook-cli.png
gitbook-cli 安装完成后开始安装 gitbook,这是两个不同的东西,然后网上有些帖子说是要执行
npm install -g gitbook //error 会报错
但实际上并不能安装成功
error.png
猜测是某些库跟当前 nodejs 版本不兼容
正确的安装方式
ln -s /root/node-v14.16.1-linux-x64/bin/gitbook /usr/bin/gitbook //设置gitbook-cli的软链接
gitbook -V //再查询gitbook-cli的版本 注意这里是大写V 然后会自动触发 gitbook 3.2.3的安装
安装gitbook报错.png
会出现一个错误,但不要紧,后面会讲怎么修复这个错误,之所以会出现这个错误,是因为 gitbook 3.2.3的版本跟nodejs 14.16.1 不兼容,据说需要 nodejs 降级为 10.23.0,这里不再去进行验证。总之,gitbook的安装条件很苛刻,这篇文章的目的并不是找出这些兼容性的搭配,而是快速找到一种完美可重现的方法供大家使用,大大减少大家在安装上的试错成本,从而将大量的时间和精力投入到真正有意义的工作上。
我们来修复这个 cb.apply 报错
//根据提示路径打开这个 polyfills_js 文件 说实在的这个路径结构有点迷
vim /root/node-v14.16.1-linux-x64/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js
使用:set number打开行号显示,注释掉62-64行,这几行是对低版本的兼容,因为不需要再做兼容,所以我们将其注释掉(这里不拘泥于vim编辑,任何一种文本编辑器打开这个js文件都可以)
:wq保存之后,再执行 gitbook -V,安装成功
注释掉三行.png
安装gitbook3.2.3成功.png
开始进入正题,启动gitbook
不要贸然相信网上所说的初始化
[root@localhost bin]# 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
这个时候并没有完全初始化成功,而只是在当前目录下生成了一个 README.md 文件
手写 SUMMARY.md 和 README.md两个文件或者git clone 网上的空白模板
mkdir book //新建一个 book 目录
cd ./book //进入 book 目录
touch SUMMARY.md
touch README.md
gitbook serve ./ //启动 gitbook
启动成功,打开浏览器 localhost:4000 进行查看,此后就是按照 markdown 语法编写 SUMMARY.md 和 README.md这两个文件,再额外添加章节md文件来愉快地进行写书了
[root@localhost book]# 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.2s !
Starting server ...
Serving book on http://localhost:4000
启动成功.png
macOS 下安装
macOS Big Sur 11.2.3及以上
nodejs官网首页.jpeg
nodejs官网首页会跟随你的系统自动显示对应的安装文件
macOS下载的是node-v14.16.1.pkg文件,直接双击文件进行安装
安装界面.png
安装对话框里也直接告诉你了node和npm的安装路径会在哪(/usr/local/bin)
安装完成后在终端里node和npm命令都显示可用
安装nodejs完成.png
然后使用下面的命令安装 gitbook-cli
sudo npm install -g gitbook-cli
注意:在macOS下一定要在前面加 sudo 否则会报错无法安装
gitbook-cli 安装完成后接下来和 CentOS 下一样,在终端输入
gitbook -V //注意V是大写
会自动安装 gitbook ,当然也会遇到和 CentOS 一样的报错
同样的错误.png
没关系,同样的错误同样的处理方法。不过在使用 vim 编辑的时候也要使用 sudo 权限
同样的处理.png
修改完这个文件后再次执行 gitbook -V 完成 gitbook 的安装
之后就和 CentOS 下的操作一样了
//在有 SUMMARY.md 和 README.md 两个文件的文件夹下执行
gitbook serve .
Windows 下安装
Windows 10
安装前需要做一些准备工作,你需要安装一款可以运行命令的终端,当然你也可以直接使用系统自带的cmd界面,这里使用的是 git-scm,安装完后鼠标右键点击桌面会多出两个 Git Gui Here 和 Git Bash Here 的菜单选项,选择 Git Bash Here 即可打开 shell 终端,其实这个 git-scm 真正的用途是一款 git 工具,不过这里就是借用了它的 shell 终端罢了
git-scm终端.png
和前面两款系统一样,Windows下nodejs官网也会跟随系统显示Windows下的安装文件 node-v14.16.1-x64.msi,下载下来后直接双击安装即可,安装过程中也可以选择安装路径
选择安装文件夹.png
和 macOS 一样,安装完成后 node 和 npm 命令直接在终端里可用,因为安装过程会自动添加环境变量
安装完成.png
然后安装 gitbook-cli 和 gitbook
npm install -g gitbook-cli
安装等待时间可能会有一点长,但最后还是能安装上的,等待总是值得的
需要等待.png
gitbook -V
等待时间还是很长,并且也会遇到 CentOS 和 macOS 下一样的错误
一样的错误.png
一样的错误就用一样的解决方法
根据错误提示的路径,找到这个 polyfills.js 文件,在 Windows下你要怎么打开这个文件就随意了,可以是记事本,也可以是任何一款代码编辑IDE
注释掉62-64行.png
保存后再次执行 gitbook -V
经过漫长等待,安装成功后在桌面新建一个 book 文件夹,然后在文件夹内手动新建两个空白文件 SUMMARY.md 和 README.md,在该文件夹的路径下启动 gitbook 就可以了
gitbook serve ./
成功启动gitbook.png
最后需要提醒的是需要注意你的 shell 终端打开的路径,就是终端标题栏那里,如果路径显示的是桌面,那么需要指定启动的文件夹是 book,启动命令如下
gitbook serve ./book
如果路径是在 book 文件夹内部,那么直接用命令 gitbook serve ./ 就好
祝大家写书愉快!
(完结)