使用GitHub和Hexo搭建免费静态Blog

前言

习惯自己写Blog的朋友一定不会陌生Wordpress，或许也曾在新浪博客和QQ空间留过脚印，但静心认真思考一下，似乎我们又总是向往更加简单自由的写作方式。GitHub给我们提供了一个无限的空间，我们需要珍惜使用，而Hexo的出现从某种意义上来说代替了Jekyll，让我们可以更专注于写作本身。本文主要介绍自己的实践心得并不断完善内容，衍生知识和原理推荐大家认真阅读官网的手册，其它推荐参考内容链接在文中也会标注出来。

阮一峰 - 喜欢写Blog的人，会经历三个阶段

第一阶段，刚接触Blog，觉得很新鲜，试着选择一个免费空间来写。
第二阶段，发现免费空间限制太多，就自己购买域名和空间，搭建独立博客。
第三阶段，觉得独立博客的管理太麻烦，最好在保留控制权的前提下，让别人来管，自己只负责写文章。

更新历史

2023年03月13日 - 升级hexo@6.3.0和node@18
2021年10月17日 - 更新macOS Node.js从16/14降级为12解决hexo g生成空文件问题
2020年09月06日 - 更新macOS下部署Hexo 5.0步骤，重构文章内容
2015年11月18日 - 推荐iissnan的主题，完善细节内容
2015年09月03日 - 完善Windows 10安装Hexo中的细节
2015年03月22日 - 更新Windows下Hexo 3.0安装和升级
2015年03月10日 - 增加Hexo 3.0降级 2.8
2014年12月19日 - 完善内容
2014年12月09日 - 更新Hexo配置修改部分
2014年06月19日 - 更新全部基础架构，待完善配置修改部分
2014年06月17日 - 更新部分Hexo建站过程，待完善
2014年05月29日 - 撰写初稿

阅读原文 - https://wsgzao.github.io/post/hexo/

---

准备工作

注意 本文主要介绍Hexo在Windows和macOS上的通用配置

了解Hexo

A fast, simple & powerful blog framework

Hexo 是一个快速、简洁且高效的博客框架。Hexo 使用 Markdown（或其他渲染引擎）解析文章，在几秒内，即可利用靓丽的主题生成静态网页。

https://hexo.io/

安装Git

https://desktop.github.com/

简单可依赖，安装完成后依据提示操作即可，So Easy

安装Node.JS

https://nodejs.org/

注意 安装完成后添加Path环境变量，使npm命令生效。新版已经会自动配置Path

;C:\Program Files\nodejs\node_modules\npm

# macOS
brew install node@18
brew link --overwrite node@18

安装Hexo

配置好GitHub家目录后，双击桌面上的Git Shell，输入npm命令即可安装

npm install hexo-cli -g
npm install hexo --save

# 如果命令无法运行，可以尝试更换taobao的npm源
npm install -g cnpm --registry=https://registry.npm.taobao.org

# macOS首次安装hexo-cli会出现权限报错
npm install hexo-cli -g

npm WARN checkPermissions Missing write access to /usr/local/lib/node_modules
npm ERR! code EACCES
npm ERR! syscall access
npm ERR! path /usr/local/lib/node_modules
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied, access '/usr/local/lib/node_modules'
npm ERR!  [Error: EACCES: permission denied, access '/usr/local/lib/node_modules'] {
npm ERR!   errno: -13,
npm ERR!   code: 'EACCES',
npm ERR!   syscall: 'access',
npm ERR!   path: '/usr/local/lib/node_modules'
npm ERR! }
npm ERR!
npm ERR! The operation was rejected by your operating system.
npm ERR! It is likely you do not have the permissions to access this file as the current user
npm ERR!
npm ERR! If you believe this might be a permissions issue, please double-check the
npm ERR! permissions of the file and its containing directories, or try running
npm ERR! the command again as root/Administrator.

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/wangao/.npm/_logs/2020-09-06T08_50_44_338Z-debug.log

# 使用以下命令修改权限解决
sudo chown -R `whoami` ~/.npm
sudo chown -R `whoami` /usr/local/lib/node_modules

# Node.js版本太高需要从18/16/14降级，否则hexo g生成的是空白文件
https://github.com/hexojs/hexo/issues/4257
https://nodejs.org/en/download/releases/

npm uninstall hexo-cli -g
brew uninstall node
brew search node
brew install node@14
brew link --overwrite node@14

npm ls --depth 0

Hexo初始化配置

Hexo官方步骤

简单几步就可以在本地执行，还有一些插件需要和第三方主题搭配使用

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

npm install hexo-generator-feed
npm install hexo-generator-sitemap

创建Hexo文件夹

安装完成后，根据自己喜好建立目录（如E:\kuaipan\GitHub\hexo），进入Git Shell切换到该路径下E:\kuaipan\GitHub\hexo执行以下指令

hexo init

#安装 Hexo 完成后，请执行下列命令，Hexo 将会在指定文件夹中新建所需要的文件。
$ hexo init <folder>
$ cd <folder>
$ npm install

#新建完成后，指定文件夹的目录如下
.
├── _config.yml
├── package.json
├── scaffolds
├── scripts
├── source
|      ├── _drafts
|      └── _posts
└── themes

安装Hexo指定版本和插件

# Hexo插件和主题要遵循版本
https://www.npmjs.com/package/hexo

# 版本
npm ls --depth 0
hexo-site@0.0.0 /GitHub/hexo
├── hexo-generator-archive@2.0.0
├── hexo-generator-category@2.0.0
├── hexo-generator-feed@3.0.0
├── hexo-generator-index@3.0.0
├── hexo-generator-sitemap@3.0.1
├── hexo-generator-tag@2.0.0
├── hexo-renderer-ejs@2.0.0
├── hexo-renderer-marked@6.0.0
├── hexo-renderer-stylus@2.1.0
├── hexo-server@3.0.0
├── hexo-theme-landscape@0.0.3
└── hexo@6.3.0

本地查看效果

继续执行以下命令，成功后可登录localhost:4000查看效果

hexo server

Hexo简写命令

hexo n #生成文章，或者source\_posts手动编辑
hexo s #本地发布预览效果
hexo g #生成public静态文件
最后我选择手动同步更新至GitHub

部署静态网页到GitHub

注册设置GitHub

1. 登录GitHub，注册自定义用户名如wsgzao
2. 在主页右下角创建New repository，name必须和用户名一致如wsgzao.github.io
3. 首次创建耐心等待10分钟左右审核，之后即可访问静态主页如https://wsgzao.github.io

同步内容至GitHub

1. 下载GitHub Windows
2. 设置Local path如E:\快盘\GitHub\
3. 运行Git Shell切换到如E:\快盘\GitHub\hexo路径下
4. 执行hexo g命令生成public文件夹
5. 把生成的内容全部拷贝到Local path或其子目录
6. 运行GitHub确认修改信息后执行右上角的Sync同步
7. 最后访问主页观察效果

https://pages.github.com/

域名和DNS

域名购买

http://www.godaddy.com/

https://www.namecheap.com/

https://wanwang.aliyun.com/domain/

DNS托管

https://www.dnspod.com/

https://www.cloudflare.com/

设置CNAME

1. 在Github的网站目录下创建CNAME文件
2. 填写自己的域名如hellodog.com，保存结束
3. 登录DNSPod，先添加域名，然后添加记录，设置如下

主机记录	记录类型	线路类型	记录值	MX优先级	TTL
@	CNAME	默认	wsgzao.github.io.	-	10
www	CNAME	默认	wsgzao.github.io.	-	10

Hexo配置修改

告诉自己为什么要选择Hexo

知识储备

1.勤学勤练Markdown

本地+云端备份数据是一种习惯

Markdown学习路径 - https://wsgzao.github.io/post/markdown/

2.使用性感的文本编辑器

工欲善其事必先利其器

• Visual Studio Code
• https://github.dev/github/dev
• https://editor.mdnice.com/
• https://markdown.com.cn/editor/
• https://markdown.lovejade.cn/
• https://editor.runjs.cool/create

Hexo主题

选择主题建议遵循KISS原则

Hexo Themes

hexo-theme-next

hexo-theme-oranges

hexo-theme-keep

hexo-theme-fluid

hexo-theme-butterfly

hexo-theme-redefine

免费图床

PicGo + GitHub + jsDelivr

https://github.com/Molunerfinn/PicGo

jsdelivr加速github图片地址格式，目前中国访问jsdelivr不稳定或者不可用

# 如何把图片放到github repo不再赘述。图片路径格式如下：
https://raw.githubusercontent.com/{user}/{repo}/master/{folderpath}/{filename}

# 如果希望使用jsdelivr的CDN，需要将上面图片路径转换为：
https://cdn.jsdelivr.net/gh/{user}/{repo}/{folderpath}/{filename}

# 或者说可做前缀替换
https://raw.githubusercontent.com/{user}/{repo}/master/
https://cdn.jsdelivr.net/gh/{user}/{repo}/

![](https://raw.githubusercontent.com/wsgzao/storage-public/master/img/202303141408339.png)
![](https://cdn.jsdelivr.net/gh/wsgzao/storage-public/img/202303141408339.png)

CDN加速github图床

https://zhuanlan.zhihu.com/p/447408685

常见问题

1. 修改配置文件时注意YAML语法，参数冒号:后一定要留 空格
2. 中文乱码请修改文件编码格式为UTF-8
3. 如何迁移至Hexo

参考文章

Hexo官方中文文档

Easy Hexo