Github博客搭建避坑指南

缘由

阿里云服务器到期，财力问题未继续付费，所以基于github免费搭建一套个人博客。
由于我非前端开发人员，本次博客系统搭建主要参考韦阳的小白搭建教程，在此感谢韦阳细致的部署教程，韦阳部署教程链接如下：

超详细Hexo+Github博客搭建小白教程

在韦阳部署教程发布时间看，实际部署在2018年4月份。距今已5年，在参考教程进行实际部署时，发现一些问题。本次我主要记录部署中出现的问题以及解决问题的过程。
其他小伙伴借鉴部署时，可先阅读韦阳的部署教程，在部署过程中遇到问题时，对照我的解决方式，希望能对大家顺利部署自己的博客有所帮助。

遇到问题：

1. github创建Pages时创建gh-pages分支
2. hexo d命令错误
3. 无法push到github远程仓库
4. 访问页面总是404
5. 访问页面不带样式

解决过程

问题1：Github创建Pages时总是创建新的分支

现象

按照韦阳教程说明：

然后项目就建成了，点击Settings，向下拉到最后有个GitHub Pages，点击Choose a theme选择一个主题。然后等一会儿，再回到GitHub Pages，会变成下面这样：

发现实际现象不同。
执行中发现一旦选择theme后，Github会默认创建一个新分支：gh-pages，并提示进行git提交申请。此时提交后GitHub Pages会将pages默认切换到gh-pages分支上，这时是没办法把gh-pages分支的内容手动迁移到master分支。

方案

方案1：不选择theme。项目建成后，点击Settings，向下拉到最后有个GitHub Pages，在Source中选择master分支，然后直接点击Save，停止后续的操作。这时候Github仓库中由于没有web资源，所以这时候访问会提示404，不过不用担心，待客户端部署后就能进行测试了。

方案2：选择theme。这时Github会创建一个新的分支gh-pages，此时可以测试访问创建的gh-pages测试创建情况。能正常打开说明创建已经完成。这时候重新进入Settings，向下拉到最后GitHub Pages，在Source中选择master分支，然后直接点击Save，操作结束。该操作后网页访问不到，不过不用担心，待客户端部署后就可恢复功能。

问题2：无法push到github远程仓库

现象

按照韦阳教程：

编写完markdown文件后，根目录下输入hexo g生成静态网页，然后输入hexo s可以本地预览效果，最后输入hexo d上传到github上。这时打开你的github.io主页就能看到发布的文章啦。

实际过程中，由于hexo会在初始化后自动创建一个hello-world.md文章，我实际部署时没有执行”写文章、发布文章“这个章节中的安装命令，导致执行hexo d后总是提示：ERROR Deployer not found: git。如下：

$ hexo d
INFO  Validating config
ERROR Deployer not found: git

方案

这个错误是由于未安装exo-deployer-git导致的，可以在博客根目录下右键打开git bash，安装对应的扩展npm i hexo-deployer-git。安装完成后再次执行hexo d后即可正常提交。

问题3：hexo d命令错误

现象

若是使用hexo自带的模板，不存在该问题，可以正常进行博客书写了。
我看到韦阳博客模板功能比较完备，所以直接使用韦阳GitHub上提供的模板，就根据韦阳的教程进行操作：

大家也可以先用下文hexo安装方法安装完hexo，然后直接git clone git@github.com:godweiyang/hexo-matery-modified.git克隆我的所有源文件，然后这是我修改完的基本没bug的定制化的博客，就可以直接拿来用啦。
我这个源文件和原来的主题没有什么区别，只是我把插件都安装完了，有些小bug也修复了，所以拿来就能直接用，方便大家。

发现执行hexo g、hexo s均正常，本地预览也正常。但是在使用hexo d提交GitHub时报错：The “mode” argument must be integer. Received an instance of Object。

$ hexo d
INFO  Deploying: git
INFO  Clearing .deploy_git folder...
INFO  Copying files from public folder...
FATAL Something's wrong. Maybe you can find the solution here: https://hexo.io/docs/troubleshooting.html
TypeError [ERR_INVALID_ARG_TYPE]: The "mode" argument must be integer. Received an instance of Object
    at copyFile (fs.js:2042:10)
    at tryCatcher (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\util.js:16:23)
    at ret (eval at makeNodePromisifiedEval (C:\Users\Administrator\AppData\Roaming\npm\node_modules\hexo-cli\node_modules\bluebird\js\release\promisify.js:184:12), <anonymous>:13:39)
    at C:\develop\hexo-theme-sungod-master\node_modules\hexo-fs\lib\fs.js:144:39
    at tryCatcher (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\util.js:16:23)
    at Promise._settlePromiseFromHandler (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:517:31)
    at Promise._settlePromise (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:574:18)
    at Promise._settlePromise0 (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:619:10)
    at Promise._settlePromises (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:699:18)
    at Promise._fulfill (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:643:18)
    at Promise._resolveCallback (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:437:57)
    at Promise._settlePromiseFromHandler (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:529:17)
    at Promise._settlePromise (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:574:18)
    at Promise._settlePromise0 (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:619:10)
    at Promise._settlePromises (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:699:18)
    at Promise._fulfill (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:643:18)
    at Promise._resolveCallback (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:437:57)
    at Promise._settlePromiseFromHandler (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:529:17)
    at Promise._settlePromise (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:574:18)
    at Promise._settlePromise0 (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:619:10)
    at Promise._settlePromises (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:699:18)
    at Promise._fulfill (C:\develop\hexo-theme-sungod-master\node_modules\bluebird\js\release\promise.js:643:18)

经查资料，普遍反馈是node.js版本不一致导致的，网上也提供了多种解决方案。

方案

方案1：The “mode” argument must be integer(node降版本方式)
网上比较常见的解决方式是降级node.js的版本号，反馈降级到比较稳定的node12.14版本后功能即可正常（个人未验证）。我特意看了一下韦阳使用的版本：v9.11.1，确实是比较老的版本了。通过降低node.js的方式我没有尝试，理论上大家普遍反馈使用该方式解决了，应该能解决问题。方法可参考：

Hexo网站部署 The “mode” argument must be integer问题

方案2：The “mode” argument must be integer(无需node降版本)
我个人不建议使用方案1降级的方式。当前node.js稳定版本是14.18.1，中间已经有了几个大版本迭代，包括安全性和新特性上来看，最好能在项目上修复该问题，使部署的项目适配最新的平台，这样后续其他项目也不至于使用旧版的node.js进行编译。继续查找资料，发现一个比较有帮助的文章：

hexo部署项目报错解决：The “mode” argument must be integer(无需node降版本)

很遗憾，通过作者的方式没能解决这个问题，不过给我很大的启示。升级hexo-renderer-stylus版本的方式没有解决该问题，但是使用hexo初始化的模板又可以正常编译、提交，那说明我个人电脑上的hexo及其他插件的版本都是没问题的，那么将韦阳项目中的版本全部升级成我电脑安装的版本是否能解决问题？
韦阳项目中的依赖版本信息：

  "dependencies": {
    "eslint": "^6.0.1",
    "hexo": "^3.9.0",
    "hexo-baidu-url-submit": "0.0.6",
    "hexo-deployer-git": "^1.0.0",
    "hexo-generator-archive": "^0.1.5",
    "hexo-generator-baidu-sitemap": "^0.1.6",
    "hexo-generator-category": "^0.1.3",
    "hexo-generator-feed": "^1.2.2",
    "hexo-generator-index": "^0.2.1",
    "hexo-generator-search": "^2.4.0",
    "hexo-generator-sitemap": "^1.2.0",
    "hexo-generator-tag": "^0.2.0",
    "hexo-helper-live2d": "^3.1.1",
    "hexo-permalink-pinyin": "^1.1.0",
    "hexo-prism-plugin": "^2.3.0",
    "hexo-renderer-ejs": "^0.3.1",
    "hexo-renderer-marked": "^1.0.1",
    "hexo-renderer-stylus": "^0.3.3",
    "hexo-server": "^0.3.3",
    "hexo-wordcount": "^6.0.1"
  }

我初始化hexo项目中的依赖版本信息：

  "dependencies": {
    "hexo": "^5.0.0",
    "hexo-generator-archive": "^1.0.0",
    "hexo-generator-category": "^1.0.0",
    "hexo-generator-index": "^2.0.0",
    "hexo-generator-tag": "^1.0.0",
    "hexo-renderer-ejs": "^1.0.0",
    "hexo-renderer-marked": "^4.0.0",
    "hexo-renderer-stylus": "^2.0.0",
    "hexo-server": "^2.0.0",
    "hexo-theme-landscape": "^0.0.3"
  }

将对应的版本升级后，最终的版本信息如下：

  "dependencies": {
    "eslint": "^6.0.1",
    "hexo": "^5.0.0",
    "hexo-baidu-url-submit": "0.0.6",
    "hexo-deployer-git": "^3.0.0",
    "hexo-generator-archive": "^1.0.0",
    "hexo-generator-baidu-sitemap": "^0.1.6",
    "hexo-generator-category": "^1.0.0",
    "hexo-generator-feed": "^1.2.2",
    "hexo-generator-index": "^2.0.0",
    "hexo-generator-search": "^2.4.0",
    "hexo-generator-sitemap": "^1.2.0",
    "hexo-generator-tag": "^0.2.0",
    "hexo-helper-live2d": "^3.1.1",
    "hexo-permalink-pinyin": "^1.1.0",
    "hexo-prism-plugin": "^2.3.0",
    "hexo-renderer-ejs": "^1.0.0",
    "hexo-renderer-marked": "^4.0.0",
    "hexo-renderer-stylus": "^2.0.0",
    "hexo-server": "^2.0.0",
    "hexo-wordcount": "^6.0.1"
  }

发现果然提交正常了。hexo d提交如下：

Enumerating objects: 380, done.
Counting objects: 100% (380/380), done.
Delta compression using up to 8 threads
Compressing objects: 100% (319/319), done.
Writing objects: 100% (380/380), 18.81 MiB | 1.91 MiB/s, done.
Total 380 (delta 66), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (66/66), done.
To github.com:gurecn/gure.github.io.git
 + 0421389...dac3b2b HEAD -> master (forced update)
Branch 'master' set up to track remote branch 'master' from 'git@github.com:gurecn/gure.github.io.git'.
INFO  Deploy done: git

问题4：访问页面总是404

这个问题我没有遇到，但是在网络上发现了。我实际测试了一下确实存在，在这里也提醒一下。
GitHub上创建的项目：username.github.io，必须使用这种格式，且username需与GitHub真实username保持一致。

• 举个反例：项目这种情况下是不行的：~~git@github.com:gurecn/gure.github.io.git ~~
• 正确例子：必须创建成这样才可以：git@github.com:gurecn/gurecn.github.io.git

通过几次尝试，我还发现一个比较好的点，GitHub显示的访问方式是：

https://gurecn.github.io/username.github.io/

实际可以使用下面的地址进行访问：

https://username.github.io/

其中username就是你的用户名。

问题5：访问页面不带样式

现象

hexo d部署后，访问对应的页面，发现博客内容确实出来了，但没有样式。所有内容跟直接显示出来，没有任何美感。

方案

经定位主要原因是GitHub访问较慢，数据没有加载完成。次要原因是浏览器可能带有缓存，一次访问失败后，后续直接加载之前错误的显示效果，无论怎么刷新都不会更新效果。
此时我发现Chrome浏览器一个比较好用的方式，点击右上角菜单，选择：打开新的无痕窗口，这个窗口不共享缓存，重新加载数据。完美解决。

好了，避坑指南到此结束，希望对大家有帮助，再次感谢韦阳细致的教程及奉献。

写在最后

以上完成后，就可以正常书写博客了。但是后续我发现还有一点比较麻烦的是，如何备份文章？或者说如果更换电脑或者多台电脑同时使用时，怎么方便的同步文章资源？
我就吃了一个大亏，电脑重装系统后，未将文章及时备份，文章原文资料丢失，无奈重新书写。后来研究，我们可以借助git版本管理工具管理我们的文章资源。

• 首先在我们必可根目录初始化git仓库，创建.gitignore忽略部署资源等相关内容：

  .DS_Store
  Thumbs.db
  .log
  public/
  node_modules/
  .deploy_git/
  .vscode/
  

• 第二步，在Github上创建一个私有仓库，用来存储我们的博客资源。
• 最后将我们的资源上传到git仓库。后续每次书写文章后，及时提交改动。
  通过该方式，实现了资源的及时备份和同步工作。