hexo搭建博客

发表于 2017-03-13 更新于 2023-08-19 分类于 other 阅读次数： Waline：本文字数： 12k 阅读时长 ≈ 11 分钟

用github + hexo来搭建自己的免费博客

GitHub Pages 快速入门 https://docs.github.com/zh/pages/quickstart

(1)　安装软件

(1.1)　安装git

在Git官网下载安装。

通过 git --version 验证是否安装正确以及查看版本。

(1.2)　安装Node.js

　在Node.js官网下载。推荐使用zip包，解压完配置一下就能用。

下载完解压到一个目录，解压文件到 D:\ProfessionalSoftWare\Node , 并在解压后的目录下建立 node_global和node_cache (node_global: npm全局安装路径 node_cache: npm全局缓存路径)

新建环境变量 NODE_PATH = D:\ProfessionalSoftWare\Node\node-v10.16.0-win-x64
修改环境变量 PATH 增加 %NODE_PATH%;%NODE_PATH%\node_global;

通过 node -v 验证是否安装正确以及查看版本。

注意：npm其实是Node.js的包管理工具（package manager），刚开始一直不知道nmp和Node.js是什么关系，晕了半天

(1.3)　配置使用

在所有程序里打开CMD，通过CMD来配置

配置git
git config --global use.name "wkq"
git config --global use.email "weikeqin.cn@gmail.com"

大家估计都有被“墙”的经历，安装hexo为了避免出现类似情况，我使用淘宝NPM镜像,输入以下命令等待安装完成
npm install -g cnpm --registry=https://registry.npm.taobao.org

使用淘宝NPM安装Hexo
cnpm install -g hexo-cli
出现WARN不用管，继续输入一下命令
cnpm install hexo --save

安装完成后，通过 hexo -v，验证是否安装正确

在cmd里进入任意目录，在该目录下创建博客，目录名可以自定义，这儿我使用blog作为博客名，
创建完该目录里就保存你博客的主要信息
hexo init blog

生成静态页面至public目录 hexo generate

部署并使用5000端口，执行完后在浏览器输入 http://localhost:5000 就可以访问博客了，端口可以自定义 hexo server -p 5000

(2)　hexo其他配置

(2.1)　RSS和站点地图

npm install hexo-generator-feed --save
npm install hexo-generator-sitemap --save
npm install hexo-generator-baidu-sitemap --save

rss、通用搜索引擎sitemap、百度爬虫sitemap

之后重启博客，访问/atom.xml和/sitemap.xml，会发现已经生成了。可以把sitemap提交到搜索引擎的站长平台来增加收录

npm install hexo-generator-search --save

npm install hexo-generator-searchdb --save

npm install hexo-renderer-stylus --save

(2.2)　添加tags页面和categories页面

tags页面是标签云
categories页面是分类

# 新建tags页面和categories页面
  hexo new page tags
  hexo new page categories

# 修改对应的index.md
edit source/tags/index.md
add line: layout: "tags"

edit source/categories/index.md
add line: layout: "categories"

delete db.json

hexo clean

hexo generate

(2.3)　添加字数统计

npm install hexo-wordcount --save

wordcount可以实现字数统计，阅读时常还有总字数的统计功能
只需要 npm install hexo-wordcount --save 就可以安装wordcount插件，
主要功能
字数统计:WordCount
阅读时长预计:Min2Read
总字数统计: TotalCount
安装完插件之后在主题的配置文件中开启该功能就可以~

(2.4)　集成Algolia搜索

npm install hexo-algolia --save

npm install hexo-algoliasearch --save

在站点的_config.yml中加入如下配置:

algolia:
  appId: 'appId'
  apiKey: 'apiKey'
  adminApiKey: 'adminApiKey'
  indexName: 'indexName'
  chunkSize: 5000
  fields:
    - title
    - slug
    - content:strip

配置环境变量HEXO_ALGOLIA_INDEXING_KEY，值为获取的apiKey，如果不知道用哪个，可以设置为 Admin API Key

(3)　域名解析

hexo blog 托管到github和coding
这么做有几个目的

增加流量，百度爬不到github的内容，但可以爬到coding的内容
国内加速
互为镜像，即使一个不能用了，还有另一个

　CNAME　www　默认　pages.coding.me
CNAME　@  　默认　pages.coding.me
　A　    www　海外　151.101.xxx.xxx (对应username.github.io的ip地址)
　A　    @　  海外　151.101.xxx.xxx

域名解析参数含义

(3.1)记录类型

　A记录：
　　将域名指向一个IPv4地址（例如：10.10.10.10），需要增加A记录
　CNAME记录：
　　如果将域名指向一个域名，实现与被指向域名相同的访问效果，需要增加CNAME记录
　MX记录：
　　建立电子邮箱服务，将指向邮件服务器地址，需要设置MX记录
　NS记录：
　　域名解析服务器记录，如果要将子域名指定某个域名服务器来解析，需要设置NS记录
　TXT记录：
　　可任意填写（可为空），通常用做SPF记录（反垃圾邮件）使用
　AAAA记录：
　　将主机名（或域名）指向一个IPv6地址（例如：ff03:0:0:0:0:0:0:c1），需要添加AAAA记录
　SRV记录：
　　记录了哪台计算机提供了哪个服务。格式为：服务的名字.协议的类型（例如：_example-server._tcp）
　显性URL：
　　将域名指向一个http（s)协议地址，访问域名时，自动跳转至目标地址（例如：将www.net.cn显性转发到www.hichina.com后，访问www.net.cn时，地址栏显示的地址为：www.hichina.com）。
　隐性URL：
　　与显性URL类似，但隐性转发会隐藏真实的目标地址（例如：将www.net.cn隐性转发到www.hichina.com后，访问www.net.cn时，地址栏显示的地址仍然为：www.net.cn）。

温馨提示：
　　搭建网站：要将域名指向主机服务商提供的IP地址，请选择「A记录」；要将域名指向主机服务商提供的另一个域名，请选择「CNAME记录」。
　　建立邮箱：需要设置「MX记录」，根据邮箱服务商提供的MX记录填写。

(3.2)主机记录

　主机记录就是域名前缀，常见用法有：
　www ：
　　将域名解析为www.example.com，填写www；
　@ ：
　　将域名解析为example.com（不带www），填写@或者不填写；
　mail ：
　　将域名解析为mail.example.com，通常用于解析邮箱服务器；
　* ：
　　泛解析，所有子域名均被解析到统一地址（除单独设置的子域名解析）；
　二级域名：
　　如：mail.example.com或abc.example.com，填写mail或abc；
　手机网站：
　　如：m.example.com，填写m。
　温馨提示：
　　要将域名example.com解析为www.example.com，在主机记录(RR)处填写www即可。

(3.3)解析线路(运营商)

　默认
　联通
　电信
　移动
　教育网
　海外
　搜索引擎

(3.4)　记录值

温馨提示：
　A记录值请填写您的服务器IP地址（必须为IPv4地址，例如：202.106.0.20），若不清楚IP，请您咨询您的空间服务商。
　如果IP地址的格式中带有端口，如：202.106.0.20:8080，则只添加202.106.0.20即可。

(3.5)　TTL

　10分钟
　30分钟
　1小时
　12小时
　24小时
　一般都选第一个，10分钟

(3.6)　我的配置

　CNAME　www　默认　pages.coding.me
CNAME　@  　默认　pages.coding.me
　A　    www　海外　151.101.xxx.xxx (对应username.github.io的ip地址)
　A　    @　  海外　151.101.xxx.xxx

(4) hexo升级

升级需谨慎

升级没有好办法，升级hexo
要换一个目录重新init，可以_config.yml可能增加了一些配置，需要自己改
source/_post下的文件可以拷过来
插件需要自己安装
可能会遇到很多意想不到的错误，不要急，慢慢解决就行

如果没有必须升级的必要，建议不要升级。

npm install hexo-cli -g
hexo init blog
cd blog
npm install
hexo server

(5)　常用命令

  npm install hexo -g #安装hexo
  npm update hexo -g #升级  

  hexo init #初始化


  hexo init  创建目录

  hexo new "postName"  # 新建文章
  hexo new page "pageName"  # 新建页面
  hexo generate  # 生成静态页面至public目录
  hexo server  # 开启预览访问端口（默认端口4000，'ctrl + c'关闭server）
  hexo deploy  # 将.deploy目录部署到GitHub

  hexo generate #使用 Hexo 生成静态文件快速而且简单
  hexo generate --watch #监视文件变动

  hexo server  # Hexo会监视文件变动并自动更新，您无须重启服务器。
  hexo server -s  # 静态模式
  hexo server -p 5000  # 部署并使用5000端口
  hexo server -i 192.168.1.1 # 自定义 IP

  hexo server -g  #生成加预览

  hexo deploy -g  #生成加部署

完成后部署
两个命令的作用是相同的
  hexo generate --deploy
  hexo deploy --generate

  hexo new [layout] <title>
  hexo new photo "My Gallery"
  hexo new "Hello World" --lang tw

  hexo help  # 查看帮助
  hexo version  #查看Hexo的版本

草稿私密博客

草稿相当于很多博客都有的“私密文章”功能。
$ hexo new draft “draft”
会在source/_drafts目录下生成一个new-draft.md文件。但是这个文件不被显示在页面上，链接也访问不到。
也就是说如果你想把某一篇文章移除显示，又不舍得删除，可以把它移动到_drafts目录之中。

(6)　遇到的错误

(6.1)　ERROR Deployer not found: git

npm install hexo-deployer-git --save 改了之后执行hexo deploy就可以了

(6.2)　Cannot set property ‘lastIndex’ of undefined

WKQ@WKQ-PC C:\blog
> hexo algolia --debug
13:34:28.423 DEBUG Hexo version: 3.3.1
13:34:28.426 DEBUG Working directory: C:\blog\
13:34:28.601 DEBUG Config loaded: C:\blog\_config.yml

...

13:34:38.088 INFO  Error has occurred during collecting posts : TypeError: Cannot set property 'lastIndex' of undefined
13:34:38.089 FATAL Something's wrong. Maybe you can find the solution here: http://hexo.io/docs/troubleshooting.html
TypeError: Cannot set property 'lastIndex' of undefined
    at highlight (C:\blog\node_modules\highlight.js\lib\highlight.js:511:35)

13:34:39.040 DEBUG Database saved
13:34:39.042 FATAL Cannot set property 'lastIndex' of undefined
TypeError: Cannot set property 'lastIndex' of undefined
    at highlight (C:\blog\node_modules\highlight.js\lib\highlight.js:511:35)

在博客的_config.yml中auto_detect设为false

遇到这种情况，首先重新clean generate 一次
如果重新clean generate后还出现这个问题，可能是哪篇博客里的内容有问题，可以用排除法解决
如果hexo clean generate时报错信息变了，那就是另一个问题了

(6.3)　Please provide an application ID. Usage: algoliasearch(applicationID, apiKey, opts)

WKQ@WKQ-PC C:\blog
> hexo algolia --debug
14:54:55.858 DEBUG Hexo version: 3.3.1
14:54:55.862 DEBUG Working directory: C:\blog\
14:54:56.037 DEBUG Config loaded: C:\blog\_config.yml

...

C:\blog\node_modules\bluebird\js\release\async.js:61
        fn = function () { throw arg; };
                           ^
AlgoliaSearchError: Please provide an application ID. Usage: algoliasearch(applicationID, apiKey, opts)
    at AlgoliaSearchNodeJS.AlgoliaSearchCore (C:\blog\node_modules\algoliasearch\src\AlgoliaSearchCore.js:51:11)
   
    at processImmediate [as _immediateCallback] (timers.js:596:5)

algolia在新版本中没有使用apiKey和adminApiKey，而是使用环境变量的方式来获取apikey，需要配置一个环境变量 HEXO_ALGOLIA_INDEXING_KEY=’you apiKey’

参考next主题有关algolia的Issues 和 algolia官方文档后
发现algolia在新版本中没有使用apiKey和adminApiKey，而是使用环境变量的方式来获取apikey，
所以要本地配置一个环境变量，
windows下计算机右键属性高级系统设置环境变量新建 HEXO_ALGOLIA_INDEXING_KEY xxx(对应的apikey) 或者可以使用dos命令行 set HEXO_ALGOLIA_INDEXING_KEY=xxx(对应的apikey)
linux下 export HEXO_ALGOLIA_INDEXING_KEY=xxx(对应的apikey)
在https://www.algolia.com/apps/${your count}/api-keys/restricted页面修改配置

(6.4)　Invalid Application-ID or API key

AlgoliaSearchError: Invalid Application-ID or API key
    at success (C:\WorkSpaces\blog_test\node_modules\algoliasearch\src\AlgoliaSearchCore.js:351:32)
    at process._tickCallback (internal/process/next_tick.js:103:7)

首先看key对不对，applicationID 有的版本里是appId
然后看value对不对，这个是自己申请的，复制就可以

(6.5)　AlgoliaSearchError: Record at the position 84 objectID=xxxx is too big size=416696 bytes.

AlgoliaSearchError: Record at the position 84 objectID=xxxx is too big size=416696 bytes. Contact us if you need an extended quota
    at success (C:\blog\node_modules\algoliasearch\src\AlgoliaSearchCore.js:335:32)
    at process._tickCallback (internal/process/next_tick.js:103:7)

AlgoliaSearchError: Record at the position 14 objectID=ad9c6969914d2c69736bd053a3d977846ffd3ac9 is too big size=159686 bytes. Contact us if you need an extended quota
    at success (C:\WorkSpaces\blog_test\node_modules\algoliasearch\src\AlgoliaSearchCore.js:351:32)
    at process._tickCallback (internal/process/next_tick.js:103:7)

博客的字数太多，文件太大，把文件大小大于41K(我测试的博客文件大小为41K时更新algolia成功的最大大小)的博客移动位置或者删除

(6.6)　AlgoliaSearchRequestTimeoutError: Request timedout before getting a response

AlgoliaSearchRequestTimeoutError: Request timedout before getting a response
    at Timeout.timeout [as _onTimeout] (C:\WorkSpaces\blog_test\node_modules\algoliasearch\src\server\builds\node.js:234:14)
    at ontimeout (timers.js:365:14)
    at tryOnTimeout (timers.js:237:5)
    at Timer.listOnTimeout (timers.js:207:5)

最后终于成功了

WKQ@WKQ-PC C:\WorkSpaces\blog_test
> hexo algolia --debug
14:33:23.642 DEBUG Hexo version: 3.3.8

14:33:25.162 INFO  [Algolia] Identified 1 posts to index.
14:33:25.164 INFO  [Algolia] Start indexing...
14:33:28.255 INFO  [Algolia] Indexing done.

(6.7)　ERROR Deployer not found: git

hexo 更新到3.0之后，deploy的type 的github需要改成git
npm install hexo-deployer-git --save

(6.8)　给博客添加feed

安装hexo-generator-feed

npm install hexo-generator-feed --save

配置到站点配置文件_config.yml

#Extensions
##Plugins: http://hexo.io/plugins/
#RSS订阅
plugin:
  - hexo-generator-feed
#Feed Atom
feed:
  type: atom
  path: atom.xml
  limit: 20

最后，在你next主题下的_config.yml下，添加RSS订阅链接即可：
rss: /atom.xml

(6.9)　给博客生成一个站点地图

安装hexo-generator-seo-friendly-sitemap

$ npm install hexo-generator-seo-friendly-sitemap --save

在站点配置文件_config.yml 中添加

sitemap:
    path: sitemap.xml

(6.10)　遇到的问题

npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@^1.0.0 (node_modules\chokidar\node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for fsevents@1.1.1: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})

这不是错误，忽略就行

参考文章

It is a warning that fseventsd.
its not an error.
its a MAC OS Specified, running on windows or Linux show this warning,this the only reason it is showing this warning, you can skip it..

(6.11)　bad indentation of a mapping entry

YAMLException: bad indentation of a mapping entry at line 9, column 4:
       - xiecheng
       ^
    at generateError (C:\blog\node_modules\js-yaml\lib\js-yaml\loader.js:165:10)

(6.12)　npm ERR! Unexpected end of JSON input while parsing near ‘…ttp”:”~0.0.2”},”_hasS’

npm cache clean --force

(6.13)　设置Hexo不渲染.md或者.html

自己写的一些html或者谷歌百度认证的html不想让hexo编译，可以通过设置 skip_render 禁止hexo编译

在 source 文件夹下的所有 md 文件或者 html 文件都会被渲染，有时候我们不想这些文件被渲染怎么办？比如很多时候我们想要写一个 README.md 或者一些自定义的页面。比如百度或者谷歌在验证站长权限的时候，通常都会要求在主目录下添加一个 html 文件。

不渲染 md 文件
使用上面的办法虽然不会渲染 md 文件，但是还是将 md 文件转化成了 html 文件，如果想保留原 md 文件后缀要怎么做呢？这就需要在站点配置文件 _config.yml 中配置，找到 skip_render 参数，开始匹配的位置是基于你的 source_dir 的，一般来说，是你的 source 文件夹下。下面我分别列举几种常见的情况进行说明：

修改博客根目录下 _config.yml ，在 skip_render 后添加以下内容。
注意：1. _config.yml 里有 skip_render，不需要再自己添加，否则会报 hexo skip_render YAMLException: duplicated mapping key
2. html里引的js文件也设置一下，禁止编译，否则会出现意想不到的错误。
3. html js 等推荐使用UTF-8编码

skip_render: README.md
# 单个文件夹下指定类型文件
  - `test/*.md`
# 单个文件夹下全部文件
  - `test1/*.html`
# 单个文件夹下全部文件以及子目录
  - `test2/**`
  - "README.md"
  - "file/**"
  - "*.html"

在不想被渲染的 html 文件最上面添加如下代码

---
layout: false
---

(7)　调优

最近这几次执行hexo generate的时候发现特别慢，特别费时间，有一次generate用了20多分钟。感觉不正常，今天正好有时间来找一下原因。
使用debug来调试，如下
hexo generate --debug

结果发现有2个原因

有一篇博客了一行有上千字，导致generate的时生成对应的index.html耗时较长，生成这个页面用了6min44s

图片里有一张test.svg的矢量图，有1.48M，特别耗时，用了18s

生成index.html 和 page/2/index.html的时候，中间花了6min53s，正好那篇博客(一行有上千字)在这两个页面里

把上千行文字删除一部分，剩50 - 200字左右就可以了
把test.svg删掉

优化前

12:29:12.409 INFO  481 files generated in 14 min
12:29:12.750 DEBUG Database saved

优化后

14:46:15.546 INFO  483 files generated in 33 s
14:46:15.741 DEBUG Database saved

wordcount也比较费时，嫌时间长可以关掉

(7.2)　优化Mathjax

加载Mathjax的过程很费时间，根据next主题的默认写法，即使在网页中并没有生成公式时, 也会加载最基本 MathJax.js。为解决此问题，可根据这篇文章的做法，只有在用到公式的页面才加载 Mathjax。

References

[1] 零基础免费搭建个人博客-hexo+github
[2] Hexo + Github Pages 搭建个人博客
[3] hexo多主题切换
[4] 为Hexo的Next主题增加畅言评论的支持
[5] Next主题官方文档
[6] Hexo 4：【高阶】NexT 主题优化之加入网易云音乐、网易云跟帖、动态背景、自定义主题、统计功能
[7] 在文章底部增加版权信息
[8] 网易云跟帖
[9] Hexo+Next主题集成Algolia搜索
[10] Hexo博客添加站内搜索
[11] 完美替代多说-gitment
[12] hexo下新建页面下如何放多个文章
[13] Hexo系列教程之三：next主题的配置和优化
[14] 分类和标签不能显示(点击)
[15] 无法生成categories和tags的页面
[16] Hexo博客优化
[17] 2017年最新基于hexo搭建个人免费博客——从零开始
[18] Valine – 一款极简的评论系统
[19] Hexo的NexT主题个性化：添加文章阅读量
[20] github pages
[21] 绑定自定义域名
[22] HEXO+Github,搭建属于自己的博客
[23] hexo官方中文资料
[24] AlgoliaSearchError: Please provide an API key. Update index fails
[25] hexo-algolia
[26] 配置algolia，跟新algolia失败 #1293
[27] 5.1.0使用algolia搜索问题 #1571
[28] 2300-algolia-record-too-big
[29] Algolia error when my index is updated #887
[30] 2300-algolia-record-too-big
[31] 为Github的Hexo博客启用SSL/TLS
[32] 给hexo加上HTTPS
[33] issues iissnan/hexo-theme-next
[34] 如何让 NexT 不默认启用 Mathjax?
[35] load mathjax only when mathjax is needed
[36] Hexo博客优化加载速度
[37] TypeError: Cannot set property ‘lastIndex’ of undefined
[38] 加速访问基于 Github Pages 和 Hexo 的博客
[39] Hexo不渲染.md或者.html

(1) 安装软件

(1.1) 安装git

(1.2) 安装Node.js

(1.3) 配置使用

(2) hexo其他配置

(2.1) RSS和站点地图

(2.2) 添加tags页面和categories页面

(2.3) 添加字数统计

(2.4) 集成Algolia搜索

(3) 域名解析

(3.1)记录类型

(3.2)主机记录

(3.3)解析线路(运营商)

(3.4) 记录值

(3.5) TTL

(3.6) 我的配置

(4) hexo升级

(5) 常用命令

草稿 私密博客

(6) 遇到的错误

(6.1) ERROR Deployer not found: git

(6.2) Cannot set property ‘lastIndex’ of undefined

(6.3) Please provide an application ID. Usage: algoliasearch(applicationID, apiKey, opts)

(6.4) Invalid Application-ID or API key

(6.5) AlgoliaSearchError: Record at the position 84 objectID=xxxx is too big size=416696 bytes.

(6.6) AlgoliaSearchRequestTimeoutError: Request timedout before getting a response

(6.7) ERROR Deployer not found: git

(6.8) 给博客添加feed

(6.9) 给博客生成一个站点地图

(6.10) 遇到的问题

(6.11) bad indentation of a mapping entry

(6.12) npm ERR! Unexpected end of JSON input while parsing near ‘…ttp”:”~0.0.2”},”_hasS’

(6.13) 设置Hexo不渲染.md或者.html

(7) 调优

(7.2) 优化Mathjax