⚠️ 阅读本文前,你需要具备:

  1. 会打字
  2. 熟练掌握Ctrl+C/Ctrl+V
  3. 或许有一点的网络知识

如果操作遇到困难,可在文章下方进行留言😃。

前言

迫不及待?建站效果实时预览:royhuang‘s blog

第一次建站时还是三年前用WordPress搭建,网站放在腾讯云VPS上运行。因为机器配置较低比较卡,有次暴躁debug把整个服务器remake了,不了了之。再后面又因为对Java Web开发比较感兴趣,折腾了SpringBoot Web开发和前后端相关知识,打算自己完全前后端自主开发一个博客。因为主客观各种原因,做了一个残次品,阴差阳错最后要以C++开始自己职业生涯第一站,也没有最终完善。

趁着这段时间,使用Hexo+Github Pages 作为最终建站方案折腾了几天,总体来说效果还比较满意。为了后来人少踩点坑,同时为自己糟糕的记忆留点回忆,特此记录。

主流建站方式比较

在正式开始前,我们不妨先来分析下主流建站方式,做到心中有数。自然,此节也可以略过。

建站难度 所需知识 定制化程度 适合人群 备注
WordPress ⭐️⭐️ Linux、Git基本知识 一般 Web开发小白人群 之前写的教程:教练,我想建网站!
Java Web ⭐️⭐️⭐️⭐️ Web前后端开发知识,多且杂 非常高,前后端代码全栈开发 Java Web开发人员
Hexo + Github Pages ⭐️⭐️ Linux、Git基本知识 较高,基于配置文件修改较方便 Web开发小白人群 不需要备案域名
Hexo + 腾讯云 ⭐️⭐️ 同上 同上 同上 域名需要备案,但网站访问速度会变快很多

根据以上,我们可以根据不同情况进行选择:

  • Java Web全栈搭建

    • 适合Java Web为技术栈的专业人员,可以作为个小项目;
    • 但如果你并非专业的Java Web开发人员,不想学习复杂的Java Web体系,但是又具备开发基础知识,想搭建一个漂亮的博客:WordPress 和 Hexo是你不二的选择
  • WordPress还是Hexo[3]

    作为都体验过的人,我说说一下自己比较主观的对比:

    • WordPress优点:很简单,适合特别小白的同学;
    • WordPress缺点:占用资源多,响应慢不支持原生markdown(每次要导出.html太痛苦了);主题也不够合心意(不美观)。

    所以我自己(有开发基础)还是推荐使用Hexo。

  • Hexo + Github Pages 还是 Hexo + 腾讯云?

    • Github Pages 托管网站:因为服务器在国外(Github),域名无需备案,但访问速度会比较慢,也无需购买云服务器;
    • 腾讯云托管网站:需要购买云服务器(或COS),且域名需要备案,但访问速度会很快。

因为本文考虑更低成本,我也比较懒不想备案,访问速度虽然慢点但还能接受,所以采用Hexo + Github Pages作为最终的建站方案。

好了,现在让我们开始激动人心的环节吧,动手搭建自己的网络快乐小窝。

Hexo + Github Pages

Hexo是一款基于Node.js的静态博客框架,依赖少易于安装使用,可以方便的生成静态网页托管在GitHub Pages上无需云服务器),是搭建博客的首选框架[2]

用大白话来说就是:

  • Hexo:用来将我们写的文章,渲染生成本地生成静态网页 ,但只有你自己能看到;
  • Github Pages : 将Hexo生成的静态网页,部署托管到云服务器(Github Pages,VPS,COS均可)上,这样别人也可以访问。

快速开始

以下主要操作均已在虚拟机中经过二次验证。

准备工作:Github & Git
  1. 创建Github个人仓库

    ⚠️ 注意命令方式必须为:你的Github用户名.github.io ,这种形式。

    image-20211202204544684

    • 登陆用户名和昵称分不清?你的个人主页,下面红框所示才是你的用户名。

      image-20211209194854716

    • 我已创建过该项目,故显示重复

  2. 安装Git

    Git下载地址 , 安装完成后,在开始菜单里找到“Git”->“Git Bash”,则Git安装成功。

    同时还需配置基本Github相关信息,主要是用户名和邮箱:

    1
    2
    $ git config --global user.name "Wanghui-Huang"    
    $ git config --global user.email "380141202@qq.com"

    本文默认你具备基本Git相关知识,故不再赘述,如果不具备可以学习:Git基础笔记

  3. 安装Node.js

    Hexo基于Node.js,自然需要安装相关组件。

    下载 Node.js , 一直默认安装即可(不要随意勾选)。

    安装成功后,分别输入 node -v & npm -v,出现以下版本信息则安装成功:

    image-20211202211811979

搭建Hexo
  1. 新建文件夹

    我们在合适的路径新建一个文件夹,命名随意,我命名为:www.hwh.zone

  2. 安装Hexo

    1
    npm install -g hexo-cli 
  3. 初始化博客

    1
    2
    cd ./www.hwh.zone/
    hexo init blog
  4. 本地测试验证

    ⚠️ 注意以下命令全部都在:./www.hwh.zone/blog 路径下执行。

    1
    2
    3
    4
    cd ./blog/
    hexo new test_my_site # 生成一篇新文章
    hexo g # 生成静态文件(网页)
    hexo s # 本地生成静态网站预览

    执行完毕后,输入:http://localhost:4000 ,出现以下页面则生成成功:

    如果hexo s 执行成功,浏览器却打不开,通常是端口(4000)被占用。可以设置hexo使用别的端口:

    1
    hexo server -p 4001

    然后输入:http://localhost:4001 ,重新打开即可。

    img

    现在你已经初步搭建好了自己的网站,现在让我们开始发布自己的网站,让更多人看到~

  5. 配置远程推送信息

    ./www.hwh.zone/blog 路径下,找到主配置文件:__config.yml

    • [注1]:因为这个文件很重要,特附图示例 。
    • [注2]:该配置文件对缩进等都严格要求,建议用IDE打开编辑(比如VScode),不易出错。
    image-20211202214234731

    在文件最下方配置相关信息:

    • ⚠️ 注意: : 后面需要留一个空格 ,repo地址最后需要带上 .git !
    image-20211202214436348
  6. 安装Git插件

    1
    npm install hexo-deployer-git --save
  7. 写一篇自己的文章

    _posts 路径下的 md 文件,会被Hexo自动解析、渲染生成网页。我们所有的博客都是放在这个目录的。

    我们在:www.hwh.zone\blog\source\_posts 路径下,写一篇属于自己的文章:

    image-20211202220312686

  8. 开始发布网站

    以上命令如果不出错,依次执行以下命令:

    1
    2
    3
    4
    5
    6
    # 清除缓存网页
    hexo clean
    # 生成静态网页
    hexo g
    # 推送发布网站,要输入Github账号和token(注意不是密码,github从上月开始已经使用token验证身份,生成token可参考:https://zhuanlan.zhihu.com/p/38800965)
    hexo d

    🐛 解决BUG:OpenSSL SSL_read:Connection was reset,erron 10054

    • 第一种情况:未解除SSL验证

      1. 打开git,切换到www.hwh.zone/blog 目录下

      2. 取消SSL验证

        1
        git config --global http.sslVerify "false"
    • 第二种情况:开了小飞机,让小飞机重新换个服务器重新连接。

  9. 欣赏你自己的网站~!

    现在我们在浏览器输入:Wanghui-Huang.github.io , 可以看到我们第一篇博客已经正式发布了!🤙

    愉快的多欣赏一下吧~

    image-20211202220438110

  10. TIPS

    💡 一般我们发布文章(或修改主题CSS样式等), 流程如下:

    • hexo clean && hexo g && hexo s ,打开 localhost:4000本地预览;
    • 本地进行修改,e.g. 文章增改、CSS样式修改;
    • F5刷新下网页即可看到修改后的文章或样式,一般不需要重新执行hexo clean && hexo g && hexo d
    • 但是如果出现刷新无效,此时最好重新执行下以上三个命令;
    • 最后再执行hexo d , 发布文章。

主题&美化:以Butterfly为例

hexo的众多开发者,无私提供了非常多主题供我们进行主题美化。去Hexo官网或在Github-hexo theme ,搜索一个你喜欢的主题:

image-20211202221852344

在这里,我使用主题 Github-Butterfly ,作为最终的选择。

快速开始
  1. 下载主题

    1
    git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

    ⚠️ 下载完毕后,文件重命名为 butterfly , 放在 www.hwh.zone\blog\themes 目录下。

    image-20211202222937528

  2. 应用主题

    在Hexo根目录下主配置文件 _config.yml , 进行配置:

    1
    theme: butterfly
  3. 安装必要插件

    1
    npm install hexo-renderer-pug hexo-renderer-stylus --save
  4. 测试查看

    重新生成静态网页:

    1
    2
    3
    hexo clean
    hexo g
    hexo d

    打开 :http://localhost:4000 , 可看到主题已经被成功替换。

    img
基本配置

如果你想参考我的配置信息,可在进行附录中查看。

在这一节我们将进行主题的基本信息设置,包括但不限于:

  • 网站基本信息设置
  • 背景图片设置
  • 目录相关设置

但是在本文并不准备将以上设置过程详细列出,因为官网对这些的描述已经非常清晰和简洁。因此,强烈建议你参考官网文档:butterfly主题配置官方文档 ,根据个人喜欢进行这些基本设置。

在这里将主要记录:官网文档未提及的优化,以及根据官网文档配置时遇到的问题解决办法

Markdowm渲染优化

本节涉及:数学公式、脚注、表情、标题大小等设置。

按照 官方文档 , 进行配置:

  1. 修改主题配置文件,加载katex.min.css

    ⚠️ per_page 属性不能设置true,否则会出现bug:公式被渲染两次。

    1
    2
    3
    4
    5
    6
    katex:
    enable: true
    # true 表示每一頁都加載katex.js
    # false 需要時加載,須在使用的Markdown Front-matter 加上 katex: true
    per_page: false # 不要选择为true!!
    hide_scrollbar: true

    然后在需要打开数学公式渲染的文章,开头设置:katex: true

    image-20211202231613955

  2. 安裝 hexo-renderer-markdown-it

    1
    2
    3
    4
    5
    npm un hexo-renderer-marked --save # 如果有安裝這個的話,卸載
    npm un hexo-renderer-kramed --save # 如果有安裝這個的話,卸載

    npm i hexo-renderer-markdown-it --save # 需要安裝這個渲染插件
    npm install @neilsustc/markdown-it-katex --save #需要安裝這個katex插件
  3. 修改Hexo根目录配置文件

    1
    2
    3
    4
    5
    6
    markdown:
    plugins:
    - plugin:
    name: '@neilsustc/markdown-it-katex'
    options:
    strict: false

表情插件配置过程如下:

  1. 安装插件

    1
    npm install markdown-it-emoji --save
  2. 根目录配置文件添加插件

    image-20211202233532272

脚注直接安装插件即可:

1
npm install hexo-reference --save

如果安装后,本地(typora)可以正确渲染,hexo无法正确渲染:多半是脚注使用出现语法错误

  • 在正文中:严格按照[^1] 写入脚注,不要用任何空格
  • 在链接中:严格按照[^1]: 写入引用链接,不要用任何空格

butterfly主题标题大小默认的过小,不易于和正文进行区分。

为此,我们需要:

  1. 找到\www.hwh.zone\blog\themes\butterfly\source\css\_third-party 路径下的normalize.min.css 文件
  2. 手动设置 h1~h5标题大小
    image-20211202234443112

标签外挂插件 Tag Plugins Plus ,提供了丰富的markdown文件编写美化

  • 时间轴
  • 各种卡片
  • 音频、视频插入

可以让你的文章看起来美观许多,具体配置请参考:Tag Plugins Plus官网

文档清晰简洁,这里不再赘述。

支持评论功能

官网文档虽然给了很多种设置的评论方式,但就我自己尝试而言,Utterances和Twikoo属于比较方便的方式。

Utterances主要优点:

  • 和Gitalk类似,但不需要过多的权限设置;
  • 相比Facebook Comments 等无需翻墙;
  • 相比Disqus等UI更简洁美观。

唯一美中不足的便是不能匿名评论,留言必须要用Github账号先登录。Twikoo在下文进行介绍。

以下是Utterances设置过程:

  1. 在Github创建一个public的项目

    不再赘述过程,我使用的是:https://github.com/Wanghui-Huang/gittalk ,这个项目。

  2. 安装 utterances

    点击:https://github.com/apps/utterances ,安装app(右上方处Install按钮)。

    安装成功后,会出现下面Configure按钮:

    image-20211203105709777

  3. 设置相关信息

    点击Configure按钮,进入设置界面,注意红框处相关信息设置:

    image-20211203105915848

    设置完毕后保存。

  4. 主题文件配置

    修改主题配置文件:repo修改为你刚刚创建的repo,形式为 你的用户名.项目名

    image-20211203110208806

    继续修改配置文件,指定评价插件名:
    image-20211203110412952

  5. 测试 & bug解决

    选择任意一篇文章,可以看到评论框已经顺利出现:

    image-20211203110741161

    经过实际测试,依旧会出现评论框无法显示的问题:

    • 我的问题是因为使用了自己的域名,https不安全便会出现这个问题;
    • 如何使用自己的域名,后续小节有详细教程 & 踩坑记录。

    可以在 Github项目:Wanghui-Huang.github.ioSettingPages ,勾选Enforce HTTPS

    image-20211203111826078

    三连重新生成静态网页:

    1
    2
    3
    hexo clean
    hexo g
    hexo s

    便可以看到评论框已经正确显示了。

虽然Utterances已经足够简洁优秀且免费,但是Twikoo基于腾讯云开发,在国内速度很快&支持匿名,价格也足够实惠(包年大约6元/月)。另一方面,支持下东家业务最后选择了这个方案。

  1. 腾讯云函数配置

    这一部分看官网文档即可,很详细不再赘述。

  2. Butterfly主题配置

    修改 主題配置文件

    1
    2
    3
    4
    5
    twikoo:
    envId: blog-comments-5g2cfs******* # 腾讯云函数配置完后的id
    region: ap-shanghai # 默认上海
    visitor: true # 显示文章浏览数
    option:
  3. 测试

    静态网页生成三连,便可以看到已经生成成功了:

    image-20211203160342989

其它补充

链接太长不好分享?

想要一个属于自己的漂漂域名?

网站发布后本地图片全挂?

在这里我们依次进行解决各种问题,让你的网络小窝看起来更加的专业。

使用短连接

hexo 默认生成文章长链接具有以下几个缺点

  1. 如果文章名包含中文,将会被转码,链接不雅观且长;
  2. 长链接不利于搜索引擎收录;
  3. 长链接不方便分享给他人。

因此,参考[4],我们利用Hexo-abbrlink插件,生成唯一文章短链接。

  1. 安装插件

    1
    npm install hexo-abbrlink --save
  2. 修改根目录配置文件

    • url:你的域名 ,如果是Github Pages命令方式为 https://你的用户名.github.io
    • permalink:按下图修改
    • permalink_defaults:注释掉

    image-20211203120905856

  3. 三连重新生成

    1
    2
    3
    hexo clean
    hexo g
    hexo s
  4. 测试

    生成完毕后,可以看到,在每一篇文章开头,自动多出了以下属性:

    1
    abbrlink: 56326  # 这个id每篇文章都不一样

    文章链接也变成了短链接的形式:
    image-20211203121301172

使用图床

使用markdown最头疼的地方,估计就是图片问题了:文章图片通常保存在本地,发布网站还是分享给他人通常还需要单独保存图片。显然,这一点也不cool。

幸运的是,我们可以使用图床,将图片通通保存在云端,本地只需像如下引用个链接即可:

1
![image-20211203121301172](https://blog-imgs-1256686095.cos.ap-guangzhou.myqcloud.com/image-20211203121301172.png)

特别的,配合Typora,所有本地图片可以自动上传到云端,可以说是很方便了。

因此,本文参考[5],使用Typora配合腾讯云COS存储搭建图床

为什么选择要付费的腾讯云COS?

在这之前我也选择了其它的免费图床,使用体验不太佳:

  • 速度很慢,而且限制一天上传的数量和频率,有时候需要集中上传本地文件的大量图片便很不友好了;
  • 腾讯云COS虽然付费,但是价格很便宜,10元可以租10G/年。

因此,最终我还是选择了腾讯云COS存储作为图床。

  1. 下载Typora

    下载地址:腾讯云高速下载 ,默认安装即可。

  2. 下载PicGo

    下载地址:官网下载 ,默认安装即可。

    image-20211203123433623

  3. 腾讯云创建COS存储

    进入腾讯云对象存储,在存储桶列表中点击创建存储桶:

    在这里插入图片描述

    设置存储信息如下:

    在这里插入图片描述
  4. 密钥管理

    密钥需要等会儿在配置文件中用到,因此我们需要提前设置好。

    在这里插入图片描述

    如果没有密钥,则新建密钥:

    • 记录以下:SecretID 和 SecretKey,等下要用到。

    在这里插入图片描述

  5. 配置PicGo

    打开PicGo后,图片上传选择腾讯云COS,然后进行以下设置:

    在这里插入图片描述

    建议域名信息也进行设置:配置管理→域名信息→访问域名,复制粘贴在最后一栏域名框中。

  6. 测试PicGO

    在左上【上传区】,任意拖拽一张图片,如果上传成功则说明配置成功。

  7. 配置Typora

    打开Typora:文件偏好设置图像

    在这里插入图片描述

  8. 测试Typora配置

    1. 在右侧栏中左下角,找到【验证图片上传选项】,测试是否成功;
    2. 打开typora,任意在文章中粘贴一张本地图片,看是否会自动上传

    以上成功,便可以愉快的开始编写文章了,开始你的大文豪生活了。

使用自己的域名

xxxxx.github.io 看起来丑丑的,怎么拥有一个自己的漂漂域名呢?

  1. 买一个属于自己的域名

    点击:腾讯云域名注册 ,注册一个自己的域名。

  2. 实名认证

    参考官方文档:域名实名认证 , 不进行实名认证可能无法进行正常域名解析。

  3. 域名解析设置

    进入腾讯云解析设置:

    image-20211203130549613

    分别添加以下解析记录:

    image-20211203130911464

    • 配置CNAME:我的域名 www.hwh.zone 可以解析到原本域名Wanghui-Huang.github.io ,这个时候 www.hwh.zone相当是个别名,也就是暴露给别人看到的名字
    • 配置A记录:可以把域名www.hwh.zone 直接解析Github IP地址 (二次保障能解析到Github IP地址)。

    不理解CNAME作用?有了A记录解析为什么还要CNAME?可参考:cname记录是什么?他存在的意义是什么?

  4. 申请免费SSL证书

    参考官方文档:域名型(DV)免费 SSL 证书申请流程

  5. Github Page设置

    在 Github项目:Wanghui-Huang.github.ioSettingPages ,设置你自己的域名 :

    image-20211203132157159

  6. 创建CNAME文件

    进入本地博客文件夹目录,例如我的:www.hwh.zone\blog\source

    • 新建文件CNAME→输入你的域名

      ⚠️ 注意:域名不要带www.

      image-20211203132639333

    • 保存文件

      ⚠️ 保存文件类型为所有文件,不是TXT文件!

  7. 测试

    网站三连发布后,浏览器输入:你的域名 ,便可以正常开始解析了。

    如果遇到错误,可以在下方评论留言。

网站备案

网站备案后通常有不少好处[6],对于个人博客来说最重要的三个便是:

  1. 加快网站的访问速度;
  2. 利于搜索引擎收录;
  3. Github Pages访问较慢,备案后可以将服务器部署到(国内服务器)腾讯云COS或者腾讯云VPS上,访问速度极大加快。

但这不影响网站域名的正常解析(除了慢点),因为毕竟网站部署在国外服务器(Github)上。

另外,网站备案经过我的尝试相比之前简便很多,只需要在腾讯云全程线上备案登记注册就好。但因为我身份证归属省份(江西),根据当地政策备案需要关闭网站,所以放弃折腾了。后续有时间补上。

写在最后

断断续续写了大概一天,终于记录完了Hexo建站的基本所有的过程。因为没怎么运动,肩膀一直隐隐酸痛还是坚持写完了,可以说是身残志坚了。

后续的话可能会继续更新这篇文章,更好的打造自己的小窝,但主要还是更新一些C++和音视频相关博文:

  • C++从零开始系列:C++基础、C++11特性学习、C++八股总结、C++开源源码分析;
  • 音视频系列:待定;
  • 其它:备案完成后,更新部署到腾讯云COS上教程。

欢迎继续关注,一起学习。

溜了表情包-溜了溜了表情包下载全套无水印--pc6下载

更新记录

2021-12-06 :更新文档

  1. 修改备案相关描述;
  2. 新增腾讯云COS相关描述。

2021-12-05 :更新文档

  1. 支持标签外挂,并新增安装教程
  2. 优化文章版式:分栏书写
  3. 更新配置文件

2021-12-01 :第一次更新

  1. 上传初稿并发布

附录

以下配置文件最终更新时间:2021/12/05 00:00 。


  1. 1.Butterfly 官方教程:https://butterfly.js.org/posts/21cfbf15/
  2. 2.Hexo 知乎教程:https://zhuanlan.zhihu.com/p/26625249
  3. 3.从wordpress到hexo:https://www.wenjinyu.me/zh/from-wordpress-to-hexo-my-blog-should-have-been-like-this/
  4. 4.Hexo-abbrlink插件生成唯一文章链接:https://zhuanlan.zhihu.com/p/112318081
  5. 5.Typora+PicGo+腾讯云COS实现图片上传功能:https://www.daimajiaoliu.com/daima/56a7c8410d4cc09
  6. 6.网站域名备案的好处有哪些?https://www.ggcx.com/news/2105/251639.html