从零开始新建Hexo博客

从零开始了解Hexo博客中已经交代了博客搭建前需要知道的最基本的信息。本篇博客对自己尝试过的搭建过程做一个总结。

需要注意:本文针对的主要是利用Hexo 和 github pages的功能新建博客。和github本身自带的github.io的博客略有区别。一个github账户只允许生成一个github.io的博客。如果还想生成其他的博客,就需要用到我这里提到的方法。过程和github.io的很像,只有一些细微的差异。

建立博客一共分几步?

网络上的各种教程给出了非常详细的步骤,可是很少有人基于自己的理解给出思路。这是一个“大象装进冰箱一共分几步”的问题。我的“大象要装进冰箱”共有五个步骤:

  1. 安装Hexo和Git本地环境的基本配置
  2. 搭建Hexo本地环境

  3. 配置网络环境

    • 运行一个github pages博客,需要保证DNS域名解析、github pages正常运转、Hexo代码可以通过github pages的服务正常打开。
    • DNS域名解析根据不同的域名供应商或者DNS解析服务供应商的不同,填写内容略有差别。
    • Gtihub Pages的配置主要是默认分支、分支名称、域名信息等内容,在这之前当然要先新建一个github的仓库了。

      • 新建分支可能需要使用的代码

        1
        2
        git branch --set-upstream-to=origin/master
        git push --set-upstream origin gh-pages
      • 新建本地文件夹并连接远程仓库的代码

        1
        2
        3
        4
        5
        git init
        git add .
        git commit -m "first commit"
        git remote add origin https://github.com/Wangjunyu/sample_hexo_blog_settings.git
        git push -u origin master
      • 新建CNAME文件代码如下,如果不太懂vi的,建议直接通过github的settings设置。

        1
        vi CNAME
      • 新建gh-pages分支

        1
        2
        3
        4
        5
        git checkout -b gh-pages
        git push --set-upstream origin gh-pages
        git add .
        git commit -m "init"
        git push
  4. 尝试生成博客

    • Hexo虽然本地环境已经准备就绪,但是还需要生成静态页面和部署页面到github对应的分支。这个步骤可不能马虎,我就是在这里摔了大坑,大部分时间都在处理这个问题,后面细说。deplyment的几个主要的操作记录如下:

      • 运行如下代码

        1
        npm install hexo-deployer-git --save
      • 修改_config 关于deploy部分内容,这里共有两段内容代码需要修改

        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        # Deployment
        ## Docs: https://hexo.io/docs/deployment.html
        deploy:
        type: git
        repo: https://github.com/Wangjunyu/sample_hexo_blog_settings
        branch: gh-pages
        # URL
        ## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
        url: http://http://hexo.junyu.pro
        root: /
        permalink: :year/:month/:day/:title/
        permalink_defaults:
      • 启动部署

        1
        hexo deploy
  5. 尝试更新博客

    • 博客搭建完成并不算完工,自己还要尝试发几篇文章试一试,确保整个过程都OK,才算是真正的完成搭建。

关键步骤

前两个步骤都比较简单,不再赘述,查看官方文档是最有效的办法,按照官方文档操作,出现问题再搜索解决问题。

配置网络环境

如果你希望自己拥有一个独立域名,需要做几件事情:

  • 购买一个域名,如果对英语不熟悉尽量选择国内的域名供应商。国外供应商在国内进行域名注册时容易遇到一些手续问题。不过托管在github的博客不太存在域名注册的问题,可以暂时忽略。
  • 找到域名解析的服务商进行解析,国内的主要有阿里云DNSPOD。一般解析为二级域名,在解析时需要填写的主要信息如下:
主机记录 记录类型 记录值
blog CNAME xxx.github.io.
  • 写CNAME文件,放到master分支;或者Settings -> GitHub Pages -> Custom domain,直接填写二级域名。注意,直接填写内容,不需要写“https://”

尝试生成博客

  • 新建gh-pages分支,并设置该分支为默认分支。该分支用于存放hexo部署时生成的静态文件。点击”Code” -> “branches” 会看到对应的设置选项。
  • 部署博客内容,用如下代码直接生成静态页面并且部署到github的gh-pages分支中。
1
hexo g -d

如果顺利,此时就可以看到你的博客了。不过不要高兴的太早,还有下面的步骤。

尝试更新博客

我就是在这个步骤上栽了跟头。因为一旦更新博客后再次部署就会出现404的错误,屡试不爽。当然最后问题解决,不然你们就不会看到我现在的博客内容了。至于那个404的错误,后面会提到。

疑难杂症

我遇到的最大的问题的现象:

博客搭建完成,看起来一切都非常的顺利。可是一旦我执行下面的代码之后,就会出现404的页面错误。而且去看gh-pages的分支中的文件完全被替换了,特别是CNAME文件也消失了。如果自己通过终端和github的代码同步之后,又会好起来。可是每一次更新博客难道都需要这样执行一遍么?

1
hexo g -d

为了解决这个问题,我进行了大量的搜索。一开始以为是分支的内容同步出现错误,后来发现是hexo部署的代码总是覆盖gh-pages的文件,以为这是配置问题。后来还找过“hexo 404”的关键字,一直没有找到非常合适的答案。不过这个过程中,自己倒是不断的熟悉Hexo的工作原理和机制。最后终于找到了关键原因:hexo在deploy时,会去_config.yml文件查找deploy的信息,如果是新建gh-pages分支的页面,会用新生成的静态网站的文件把gh-pages分支下的文件全部替换。

最终解决问题的办法很简单:

  1. 不在gh-pages上传任何网站的源码,仅仅用来存储静态网页。
  2. 源码依然在这个仓库,不过是放在master分支下
  3. 把CNAME文件放到“source”的子目录下,这样可以保证文件在生成静态文件时再次上传。
  4. 注意:任何gh-pages下的文件都会被替换,所以一定要在非gh-pages的分支下存放源码,或者在其他的仓库里操作,最终部署到这里。

其实在这个过程中还遇到了一个让我非常非常费解和奇怪的问题,对于新手来说,如果你严格按照前面的步骤操作,不会遇到这个问题。如果不幸中招,可以查看重建Hexo的教训解决问题。

推荐阅读&Reference

声明: 本文转载需标明出处,禁止用于商业目的。

ChangeLog

20161108 新建文档
20161108 发布文档