在GitLab CI中构建GitBook的各种坑

发表于 2021-01-25 分类于教程

GitBook是一个好用的文档工具，然而他们已经转型在线敛财，留下的开源的框架已经弃坑。我们用GitLab CI（或其他自动构建系统）构建，则会有很多的坑。本文梳理了会遇到的各种坑。

GitBook的各种坑

卡在 Installing GitBook 3.2.3

这个是国内网络问题，直接换用淘宝源即可：

npm config set registry https://registry.npm.taobao.org

通常情况下，这样是不够过瘾的，所以要换得全一些，免得再踩坑：

npm config set registry https://registry.npm.taobao.org
npm config set disturl https://npm.taobao.org/dist
npm config set sass_binary_site https://npm.taobao.org/mirrors/node-sass
npm config set electron_mirror https://npm.taobao.org/mirrors/electron/
npm config set puppeteer_download_host https://npm.taobao.org/mirrors
npm config set chromedriver_cdnurl https://npm.taobao.org/mirrors/chromedriver
npm config set operadriver_cdnurl https://npm.taobao.org/mirrors/operadriver
npm config set phantomjs_cdnurl https://npm.taobao.org/mirrors/phantomjs
npm config set selenium_cdnurl https://npm.taobao.org/mirrors/selenium
npm config set node_inspector_cdnurl https://npm.taobao.org/mirrors/node-inspector
npm config set node_sqlite3_binary_host_mirror https://npm.taobao.org/mirrors

yarn config set registry https://registry.npm.taobao.org
yarn config set disturl https://npm.taobao.org/dist
yarn config set sass_binary_site https://npm.taobao.org/mirrors/node-sass
yarn config set electron_mirror https://npm.taobao.org/mirrors/electron/
yarn config set puppeteer_download_host https://npm.taobao.org/mirrors
yarn config set chromedriver_cdnurl https://npm.taobao.org/mirrors/chromedriver
yarn config set operadriver_cdnurl https://npm.taobao.org/mirrors/operadriver
yarn config set phantomjs_cdnurl https://npm.taobao.org/mirrors/phantomjs
yarn config set selenium_cdnurl https://npm.taobao.org/mirrors/selenium
yarn config set node_inspector_cdnurl https://npm.taobao.org/mirrors/node-inspector
yarn config set node_sqlite3_binary_host_mirror https://npm.taobao.org/mirrors

但是，到了CI服务器上，这样有可能还会卡Installing，所以我们可以考虑提前手工把这个3.2.3装好（位于~/.gitbook/versions/3.2.3）：

mkdir -p ~/.gitbook/versions
cd ~/.gitbook/versions
npm pack [email protected]
tar -xvf gitbook-3.2.3.tgz
mv package 3.2.3
cd 3.2.3
npm i

# 防止踩后文提到的一个坑
npx npm i cpr@3

安好之后把它打包上传到服务器里面，然后我们需要设法让CI每次构建之前都能找到这个文件。

假设GitLab CI Runner基于Docker，那么有两种处理方法： * 一种是把3.2.3文件也传到代码里，然后在构建步骤中增加类似mkdir -p ~/.gitbook/versions; ln 3.2.3 ~/.gitbook/versions的操作。但是大家都知道光处理一个node_modules就会耗费大量时间，所以除非没权限操作服务器，否则不太推荐。 * 如果有服务器权限的话，最简单的办法就是设置一个Volume，把3.2.3所有文件提前装好放到某个位置（例如/data/gitlab-runner-gitbook-cache/versions/3.2.3），然后修改Runner的config.toml：

[[runners]]
  ...
  [runners.docker]
    ...
    volumes = [
      ...
      "/data/gitlab-runner-gitbook-cache:/root/.gitbook",
    ]

说到config.toml，顺便提一下，/root/.npm和/cache也可以顺便在服务器本机缓存一下，避免每次创建容器时都重新下载，从而提高构建速度。

报错，TypeError: cb.apply is not a function

报错全文：

/usr/local/lib/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 /usr/local/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18
    at FSReqCallback.oncomplete (node:fs:194:5)

解决方法有两种： * 将Node.js降级为版本10.x * 找到报错的源头，即polyfills.js文件的第287行，将这个函数直接改成

function statFix (orig) {
  return orig
}

鉴于我们要通过CI来构建，推荐使用第一种解决方法。

莫名其妙地找不到文件

错误信息：

Error: ENOENT: no such file or directory, stat '/builds/xxxxx/xxxxx/_book/gitbook/gitbook-plugin-xxx/xxx.js'

如果你多试几次，可能会发现每次报错的文件都不一样。

如果GitBook 3.2.3是手工安装的，需要进到安装目录里，补一条命令，例如：

cd ~/.gitbook/versions/3.2.3
npx npm i cpr@3

自动安装（如果你不嫌卡Installing GitBook 3.2.3）则需要提前gitbook fetch 3.2.3，然后在正式build之前执行上面两行命令（当然建议写成一行(cd ~/.gitbook/versions/3.2.3 && npx npm i cpr@3)，命令两端有括号）。

左侧的文档目录未更新

是不是使用summary插件自动生成目录了？如果是，每次build两遍就好了。

参考操作

手工安装GitBook 3.2.3

参见前文。

package.json

仅列举部分内容：

{
  // ...
  "scripts": {
    "serve": "gitbook serve",
    "build": "gitbook build"
  },
  "dependencies": {
    "gitbook-cli": "^2.3.2",
    "gitbook-plugin-editlink": "^1.0.2",
    "gitbook-plugin-prism": "^2.4.0",
    "gitbook-plugin-search-pro": "^2.0.2",
    "gitbook-plugin-summary": "^1.1.0",
    // 其他插件...
    // 唯独不能放 gitbook，否则会报错
  }
}

.gitlab-ci.yml

stages:
  - build
  - deploy

variables:
  PROD_DEPLOY_USER: root
  PROD_DEPLOY_HOST: x.x.x.x
  PROD_DEPLOY_PORT: 22
  PROD_DEPLOY_PATH: /var/www/html
  # PROD_DEPLOY_SSH 在 GitLab 的 Settings -> CI/CD -> Variables 中配置

build:
  stage: build
  image: node:10      # 此处要使用版本10

  script:
    - npm config set registry https://registry.npm.taobao.org
    - npm config set disturl https://npm.taobao.org/dist
    - npm i
    - npm run build
    # 使用summary插件生成目录的话，需要build两遍才能显示新版的目录
    - npm run build

  cache:
    paths:
      - node_modules/

  artifacts:
    paths:
      - _book
    expire_in: 1 week

  only:
    - master

deploy:
  stage: deploy
  image: sebble/deploy
  script:
    - mkdir -p ~/.ssh
    - echo "$PROD_DEPLOY_SSH" >> ~/.ssh/id_dsa
    - chmod 600 ~/.ssh/id_dsa
    - echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config
    - rsync -rav -e "ssh -p $PROD_DEPLOY_PORT" _book/ "$PROD_DEPLOY_USER"@"$PROD_DEPLOY_HOST":"$PROD_DEPLOY_PATH"
  only:
    - master

参考资料

https://github.com/GitbookIO/gitbook-cli/issues/55