hexo博客搭建时遇到的一些问题

之前的WP博客荒废了好久之后终于感觉该做点正事了,所以这几天花了点时间重新弄了下hexo,毕竟是比较符合前端的一个博客框架。比起wp来说,hexo轻量级的多,而且易部署(指速度优化方面),也不需要一个专门的服务器来放置(这个其实是我选择hexo的最终原因。手里虽然有vps,但是因为跑着ss加上国内ping值太高,最终肯定影响国内速度,所以就一直没用来放blog)当然没有后台也就意味着不能随时随地写了就发,这个相对WP来说是弱势,但我感觉还好,毕竟不会常常在外面跑,而且写博客基本都是在电脑前,再不济也可以先把MD文件写完后拷回去发布。


先大概说下我目前blog的部署方式:

  • github和gitcafe双线路部署,国内线路解析到gitcafe,国外线路解析到github。
  • 自己的域名且未备案(个人博客不建议备案)
  • 域名解析采用dnspod国际版(这个很重要,后面会解释
  • 使用QQ的自定义域名邮箱
  • 图片采用七牛存储分流
  • 多说评论有一定优化(显UA以及自定义样式等)

然后下面说下我部署过程中遇到的部分问题以及相应的解决方法,由于我自己是Windows 7环境,所以下面很多解决方法可能对*nix党不适用,还请注意。问题的排列按照最基础的node安装,git配置,域名配置,hexo安装,hexo优化美化的顺序来,不过会跳过很多可以直接百度到的内容,所以建议参考Hexo常见问题解决方案以及hexo你的博客如果你遇到的问题我这里没提到的话,你可以去这两篇文章搜下解决方案。


npm安装hexo速度过慢

由于某些大家都知道的缘故,npm官方源在国内的下载速度极其慢,用官网的npm install hexo-cli -g速度非常感人,所以不推荐这种方式。这里我推荐用淘宝的npm分流——cnpm
安装过程很简单:
npm install -g cnpm --registry=https://registry.npm.taobao.org
然后等着装完即可,之后的用法和npm一样,无非是把npm install改成cnpm install,但是速度比之前快了不止一个数量级(不过下文为了方便理解,还是会用默认的npm安装,如果你发现速度不好的话,请自行替换成’cnpm’)

npm安装tips

  1. npm安装的时候有时候会出各种错,而最常见的无非是权限问题、网络连接、包名输错。注意看cmd窗口的报错信息即可。
    windows党请注意安装的时候将cmd用管理员方式打开(这个是我见过报错最多的),想必npm ERR! Please try running this command again as root/Administrator.各位也不是第一次见了
  2. hexo插件安装的时候先cd到blog根目录,并且安装参数不要带-g。 (即不要全局安装,因为全局安装的时候插件会被装到node的根目录下去,而不是blog目录),hexo的插件需要在blog目录下才能工作
  3. 有部分hexo插件用普通的install可能会出现安装完的版本和最新版本有区别,而且怎么也升级不上去的情况(npm update无效),这种情况下请手动指定版本安装:
    语法:
    npm install [@<scope>/]<name>@<version>
    例子:
    npm install hexo@3.1.1 --save

git多网站ssh部署方案

因为是gitcafe和github多线路部署,加上不想每次更新的时候都输帐号密码,所以https传输肯定不行了,只能是ssh传输。不过大部分教程都是单网站部署。所以特地把这个单独拿出来。建议参考gitcafe的这篇部署教程,一般人看完应该就不需要看我这底下的内容了,我这里步骤都复制以上教程,仅对部分地方加点我个人感觉比较重要的注释
git客户端安装的时候可以选择要不要集成到cmd里,有些人可能和我一样没有集成,导致cmd对部分linux下的命令无法解析(比如~)
强烈建议以下操作在git bash里进行。不要在cmd里敲git命令!
强烈建议以下操作在git bash里进行。不要在cmd里敲git命令!x2
强烈建议以下操作在git bash里进行。不要在cmd里敲git命令!x3
因为很重要所以说三遍

  1. 生成新的 SSH 秘钥
    记得把以下命令中的 YOUR_EMAIL@YOUREMAIL.COM 改为你的 Email 地址
    ssh-keygen -t rsa -C "YOUR_EMAIL@YOUREMAIL.COM" -f ~/.ssh/gitcafe

    上面最末尾的./ssh/gitcafe中的’gitcafe’即为存在本地的密钥文件名,所以这里是可以自定义的。
    密钥文件本地存放路径为git的home参数对应路径下的.ssh文件夹,一般是”C:/Users/[username]/.ssh”,如果没有找到的话到git bash里输入$HOME回车然后自行去对应目录查找即可

  2. 生成过程中会出现以下信息,按屏幕提示操作,并记得输入 passphrase 口令。

    $ ssh-keygen -t rsa -C "YOUR_EMAIL@YOUREMAIL.COM" -f ~/.ssh/gitcafe
    Generating public/private rsa key pair.
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /c/Users/username/.ssh/gitcafe.
    Your public key has been saved in /c/Users/username/.ssh/gitcafe.pub.
    The key fingerprint is:
    15:81:d2:7a:c6:6c:0f:ec:b0:b6:d4:18:b8:d1:41:48 YOUR_EMAIL@YOUREMAIL.COM

    这将在 ~/.ssh/ 目录下生成 gitcafe 和 gitcafe.pub 文件,记住千万不要把私钥文件 gitcafe 透露给任何人。

    passphrase的作用是在密钥传输的过程中加一个解密钥的过程,使得即使密钥文件不小心泄露了,别人也不能直接利用密钥操作你的git帐号,但是由于我个人处理不了ssh-agent自动填充的问题,导致每次更新git都要输passphrase,所以我就没加了,上面的过程里是直接两次回车过去了。

  3. 在 SSH 用户配置文件 ~/.ssh/config 中指定对应服务所使用的公秘钥名称(config文件的作用就是告诉git程序在同步认证的时候该使用哪个密钥),如果没有 config 文件的话就新建一个,并输入以下内容:

    Host gitcafe.com www.gitcafe.com
      IdentityFile ~/.ssh/gitcafe

    由于是gitcafe和github双站,所以这里需要再参考上面的语法另外建立一个github的规则(贴下我个人的config文件内容供参考)

    Host gitcafe.com
    IdentityFile ~/.ssh/gitcafe
    
    Host github.com
    IdentityFile ~/.ssh/id_rsa
    
    Host git.oschina.net
    IdentityFile ~/.ssh/chitanda_osc
  4. 添加 gitcafe.pub 中的内容到 GitCafe 网站。
    具体请参考如何安装和设置 Git中的第三节。

  5. 最后测试配置文件是否正常工作

    ssh -T git@gitcafe.com

    如果连接成功的话,会出现以下信息。

    Hi USERNAME! You've successfully authenticated, but GitCafe does not provide shell access.

    对于这一步,我的建议是测试命令里再加个-v参数,即

    ssh -vT git@gitcafe.com

    因为比起”ssh -T”返回的模糊信息相比,”-v”会把整个传输过程中的操作都显示出来,哪一步出错很明显就可以看出来,利于出现问题的调试

  6. 完成
    测试通过后,你就可以使用独立的一套公秘钥来使用 GitCafe 了。Enjoy!

单域名多线路解析

这个解决方法来自v2ex的”wy315700”,感谢指点
由于网站未备案,所以不能直接放在七牛上(不过如果全部放在七牛,也就失去了双线路的部署意义,所以我个人感觉没必要全站七牛)
先科普一些域名相关的小知识:

  1. 关于A解析和CNAME解析的区别:

    A解析:只能填IP地址,IP地址如果换了的话就需要换解析记录
    CNAME解析:解析到另一个域名,即使被指向的域名的ip发生变化,也不需要更改解析记录。CNAME优先级高于A解析(至少在DNSPOD是这样的)

  2. 域名的nameserver(一般简称”NS”)

    nameserver的作用是指定域名的dns解析服务商,比如同时在万网和dnspod给”www.a.com”做了解析,那么哪个解析起作用,就是由NS来决定的。这个在域名注册商的域名管理的里可以更改。NS记录建议只写一个dns解析商的,多NS可能会有问题,可以参考这篇文章
    DNSPOD国内版本目前只对国内线路做细分,没有海外线路的选择,所以不推荐,建议用dnspod的国际版

操作流程:

  1. 注册dnspod国际帐号
  2. 域名服务商那里更改ns记录为dnspod国际版的nameserver,默认为

    a.dnspod.com.
    b.dnspod.com.
    c.dnspod.com.
  3. 在dnspod添加域名解析:
    先加一条cname解析国内线路给gitcafe,然后再加一条默认线路的cname给github即可完成双线路解析

  4. github自定义域名需要在项目根目录下添加一个CNAME文件,文件内容为自定义域名。CNAME文件创建完之后扔到blog/source目录下即可 (不能直接扔到public下,理由见下文)
    gitcafe需要在项目做设置,具体参考官方wiki

自定义域名邮箱

比如i@chitanda.me这种邮箱,目前我用的QQ的域名邮箱,免费,不过我这边会遇到有时候gmail丢件的问题,所以准备看看过段时间转zoho。
具体实现很简单,就是域名解析里加条mx记录,不做详细解释,可以参考QQ域名邮箱的帮助(由于通配的mx记录和cname会有语法冲突,有些dns解析商是不支持这种写法的,但是dnspod对语法要求不严格,可以这么写。所以这也是我推荐dnspod的另一个缘故)
另外有些域名服务商可能免费送了mail服务,也可以用自带的那个。我由于域名注册在name.com上,它们没送,所以只能另外想办法

hexo部署相关问题

首先需要明确一点,public目录下的文件每次’hexo -g’的时候就会被重新生成,所以不要往这里面放任何东西,不然每次都要另外加。
而blog/source和blog/theme/[theme-name]/source里的文件是不会被另外处理的,所以有些需要添加在网站根目录的文件(如favicon,谷歌百度的站点认证文件之类的)可以直接扔到这两个文件夹底下,具体选哪个路径要视情况而定

_config.yml编译不通过

yml语法极度严格,不通过往往是空格问题,记得所有设置参数属性末尾都要加空格

给网站添加favicon

这个和主题有关,默认可能没有,浏览器打开后根据开发者工具里可以看到当前主题下’favicon’的具体路径和要求文件格式,对应做一个就可以了。有时候是’png’但也有时候强制要求’.ico’,可以去比特虫d等网站在线制作。

github和gitcafe双线路解析

安装hexo-deployer-git的0.0.4版!
安装hexo-deployer-git的0.0.4版!
安装hexo-deployer-git的0.0.4版!
很重要所以说三次。我之前安装的时候默认都是0.0.3版,哪怕其实0.0.4已经出来了。而即使是完全正常的配置,0.0.3版都会提示”fatal: Unable to create ‘XXXXXX/.git/index.lock’: File e
xists.”(固定版本安装办法可以看上文)
查看当前已安装版本:

npm ls hexo-deployer-git

附正确配置:

deploy:
  type: git 
  message: "xxxxx"
  repo: 
    github: git@github.com:chitanda/chitanda.github.io.git,master
    gitcafe: git@gitcafe.com:chitanda/chitanda.git,gitcafe-pages

跟在”,”后面的是分支名字。注意传输地址应该是ssh格式的,不要弄成了https的地址

多说评论框自定义

其实从评论质量来说的话,disqus可能更好点(毕竟是gfw认证网站,相比多说门槛稍微高一点,可以过滤部分人群),不过拖累网页加载速度,所以我就换成多说了。
多说样式可以后台自定义css,本站的多说css来自Next.Mist主题制作者的样式
显UA功能需要改多说的js,具体参考此文
单说”Next”主题下改完embed.js后需要做的事情:
“Next”主题内嵌多说,所以需要更改主题文件:
打开/themes/next/layout/_scripts/comments/duoshuo.swig,更改”embed.js”的文件路径即可。这里我是把js扔到7牛上去了,你也可以直接放到主题里然后更新到gitpage上去。

图片资源利用七牛分流

由于git-page自带空间只有300M,看起来博客够用了,但是总觉得憋得慌,对于全图片直接扔上去这种事个人没太大信心,所以决定图片用七牛分流(虽然这样某种意义上对双线路部署的做法产生了消极影响,不过考虑到七牛的CDN速度以及资本主义国家的网速加上未雨绸缪的300M空间,最终还是决定图片传到七牛上去)

我最初的办法是用hexo的一个插件(hexo-qiniu-sync)
但是后来发现这个插件效率不高,一开整个hexo的反应都慢了,而且最主要一点是失去了MD文件的通用性,所以最终弃用该方法。
另外采用了一个本地同步文件到七牛的插件qiniu4blog,使用很简单,具体可以看文档。

多PC的情况下blog备份问题

本来想用网盘的自动备份工具,但是考虑到blog的posts文件夹在写文章时的更新频率,我又放弃了这种做法。
另外由于”_config.yml”里有七牛的密钥数据,所以整个blog文件扔到git上也是不可取的。个人建议还是打个包直接另一台电脑解压吧(一般来说拷贝source文件夹,theme文件夹,静态资源文件夹以及站点配置文件即可)。

上面删除线内的是我对备份的最初想法,然后实际使用后发现有至少两个缺点:

  1. 麻烦,每次另一台电脑上都要从百度云下载更新文件夹手动覆盖
  2. hexo s开启本地服务器状态的时候,会对文件夹进行监视,动态编译生成的文件,而百度云的自动备份会在你每次保存文件的时候都生成一个.cfg文件,导致hexo编译失败,然后就会停止本地服务器解析,又要手动开启一次(写文章的时候随时顺手CTRL+S是个好习惯)

以上两个原因导致了”百度云备份”这个方案被否决,所以最终还是回到了git备份的路子。由于blog全站备份,所以建议放私有仓库,另外根目录下_config.yml尽量不要放上去(有些插件比如我现在在用的”hexo-qiniu-sync”就有七牛的key,所以不建议同步到git上)
这里写起来篇幅可能比较长,所以我另外写了一篇文章单独来讲同步:
hexo博客多PC间同步解决方案

可以参考。

需要注意的事,不管这台电脑上之前有没有安装过hexo,安装完成后都是不需要hexo init的——这个操作会把config初始化。。
直接在复制过来的blog文件里运行hexo的命令即可。不过hexo插件都需要重新安装下。

给github添加README

众所周知hexo会把文件夹内的所有md文件解析成html,而github的readme只支持MD格式。(所以想在这里直接插html绕过限制的就只能说残念了)
网上之前很多方法,不过都没有说到点子上,因为即使把README.MD文件放到source或者theme对应的source文件夹下,再加上layout:false,hexo还是会把文件解析掉。
另外有一种不怎么优雅的解决方法是把'README.MD'的后缀去掉,改成'README',不过这样的话github只能支持部分解析,不会当做一个完整的MD文件来处理,样式上和期待值有差别

正确的解决方法其实很简单:

**把’README.MD’文件的后缀名改成”MDOWN”然后扔到blog/source文件夹下即可,这样hexo不会解析,github也会将其作为MD文件解析

效果可参考我这个github的主页

文章添加代码块有注释时的高亮

建议对应代码块语法选择相应的注释符号。比如html<!-- -->,css/* */,否则可能会出现代码不高亮或者高亮有问题的情况。

MarkDown里 table 的语法

MD写法:


| 链接 | 结果 | 原因 |
|:-----|:---:|----------:|
|文本内容| **`是`** |同协议同域名同端口|
|文本内容| **`是`** |同协议同域名同端口|
|文本内容| **`是`** |同协议同域名同端口|

  1. 最上面一行是表格第一列的值。第二行的冒号位置决定表格内文本的对齐方式。有水平居中水平靠左对齐水平靠右对齐三种.
  2. 切记表格要与上面的文本内容空一行。否则解析不出来
  3. 每列的宽度是根据对应列里最长的文本来决定的

输出结果:

链接 结果 原因
文本内容 同协议同域名同端口
文本内容 同协议同域名同端口
文本内容 同协议同域名同端口

以上是之前我之前部署的时候有遇到过的一些问题,后面会视情况再不定时更新下。希望对看到这篇文章的人有所帮助