使用Hexo搭建自己的博客网站
1. 背景介绍
-
本文是写给完全没有接触过技术的普通博客用户使用的,所以解释地比较细致,如果有技术基础,可以忽略其中的解释部分,按命令执行即可.
-
说明:我的工作环境是 fedora linux, 出于安全性考虑一直运行在普通用户下, 如果你的安装环境是 Mac 或者 windows,请理解每一步骤的含义后执行调整命令和参数.
或者在我的博客下面留言,我有空的时候会统一回复. -
说说我为什么选择 Hexo, 目前比较主流的博客生成系统有三个 hexo, jekyll 和 hugo,jekyll 是老牌的博客生成系统,受到了 github 官方的支持,但是是用的 ruby 的技术栈,
我是技术出生, 但是 ruby 一直不在我的技术栈范围之内,至于 jekyll 和 github 在部署的时候的结合度更高的问题,我想对于一个做技术的人来说应该不是什么难事,应该比较容易解决.
相比之下 hexo 使用的 nodejs 技术栈,hugo 是 golang 技术栈这两块技术栈我都比较熟悉,主要在这两个博客生成器系统之间徘徊.hugo 固然速度更快,github 上获得的星星数量也更多一些.由于考虑到博客系统更偏向于前端技术,这一块为 nodejs 所擅长,很多库都可以重用。从自己的职业嗅觉,我觉得一个静态博客系统或博客生成器采用 nodejs 技术栈更合适一点,另外很重要的一点 Hexo Theme 显得更成熟一些,所以我选择 Hexo, hexo 和 hugo 现在也很难说谁会在这一领域最终胜出.经过调查发现即使将来 hugo 胜出,迁移到 hugo 成本也不会太高.就我目前的个人需求和兴趣点来说,我还是比较偏向 Hexo.
本文原文位于使用 Hexo 搭建自己的博客网站, 如需获取最近更新,以及遇到 markdown 排版问题,请访问原文,以获得最佳阅读体验。
2. 前提条件
-
需要先安装 nodejs 的相应版本
-
发布博客需要注册 github 账号
3. 安装 Hexo
在安装 Hexo 首先需要了解 hexo 版本与 nodejs 版本的兼容性,避免安装之后出现版本兼容性问题。
详情参考Install-Hexo。
Hexo version | Minimum (Node.js version) | Less than (Node.js version) |
---|---|---|
7.0+ | 14.0.0 | latest |
6.2+ | 12.13.0 | latest |
6.0+ | 12.13.0 | 18.5.0 |
5.0+ | 10.13.0 | 12.0.0 |
4.1 - 4.2 | 8.10 | 10.0.0 |
4.0 | 8.6 | 8.10.0 |
3.3 - 3.9 | 6.9 | 8.0.0 |
3.2 - 3.3 | 0.12 | unknown |
3.0 - 3.1 | 0.10 or iojs | unknown |
0.0.1 - 2.8 | 0.10 | unknown |
3.1. 安装 nodejs
首先需要安装 nodejs, 可以参考我以前写的一篇博文安装并配置 nodejs,需要从以上表格中找到对应的版本进行替换。
3.2. 安装 Hexo 命令行工具
sudo npm install hexo-cli -g
或者
#(推荐使用cnpm安装, 速度快)
sudo cnpm install hexo-cli -g
说明:
npm 是 nodejs 的包管理工具,sudo 是 linux 或 unix 下将命令以管理员身份运行, windows 环境下不需要 sudo,install 为 npm 子命令用于安装工具包或项目依赖
-g 为全局安装,安装一次后,在命令行中处于任何目录位置都能使用,如果不带-g 工具包被安装在当前项目的 node_modules,
需要借助 npx 才能执行相关命令,像 hexo-cli 这样的命令行工具建议全局安装
这一步需要管理员权限,sudo 即为以超级用户运行安装命令,linux 和 mac 安装方法相同
如果是 windows 环境可能需要以管理员身份运行,可以将 sudo 去掉, windows 下如果需要管理员权限,会弹出请求授权框
即npm install hexo-cli -g
或者cnpm install hexo-cli -g
如果访问墙外资源较慢,可以是 cnpm 经过阿里的镜像安装 hexo-cli 命令行工具,cnpm 前面的 c 即为 china 的意思,wall 内专用 nodejs 包管理工具
4. 创建博客系统
4.1. 初始化博客系统
# 创建博客目录(blog为目录名,可以根据自己的喜好进行调整)
mkdir blog
# 进入博客目录
cd blog
# 初始化hexo
hexo init blog
命令说明:
hexo: 是 hexo 的命令
init: hexo 的子命令,用于初始化一个博客系统.
blog: 是博客系统的名字,这里我没有考虑太多,直接将博客系统的名字命名为 blog, 你可以根据自己的喜好设定名字.
进入 blog 目录,安装项目依赖包(第三方 nodejs 类库或工具)
# 安装nodejs依赖包
npm install
初始化完成后的简要目录结构如下:
./blog
├── _config.landscape.yml
├── _config.yml
├── db.json
├── node_modules
├── package.json
├── package-lock.json
├── scaffolds
├── source
└── themes
4.1.1. 目录结构说明
-
package.json: 这个是 nodejs 要用到的,里面存放着项目信息,版本,项目所依赖的第三方 nodejs 工具和代码库
-
package-lock.json: 这个 nodejs 解析依赖包时会用到的
-
scaffolds: 博客脚手架,当你创建新的博文时可以基于其中的某个模板进行修改.
-
source: 源代码文件夹,这里存放你网站的内容.
-
themes: 主题,博客 css 样式,背景图片等等.
-
node_modules: 这里存放 npm install 时从网络下载下来的依赖包
-
config.yml 项目配置文件
-
配置文件详细说明
-
这里重点说明一下项目配置文件.
-
你可以修改项目的默认配置文件_config.yml 以满足你个人的需求.比如标题,网站的描述,搜索关键字等等一些信息
| setting | chinese | desc | | :------------- | :-------------- | :--------------- | | title | 标题 | 你网站的标题 | | subtitle | 子标题 | 你网站的子标题 | | description | 网站描述 | 你网站的描述信息 | | keywords | 关键字 | 关键字 | | author | 作者 | 网站的作者 | | language | 语言 | 网站支持的语言 | | timezone | 网站时区 | 网站时区 | | theme | 主题 | 使用的主题名称 | | per_page | 每页文章数量 | 每页显示的文章量 | | pagination_dir | 分页url | 指定博客生成后,每页的 index.html 文件存放目录 |
-
5. 本地启动博客系统
当前目录下执行以下命令,启动博客系统.
hexo serve
如果启动成功,会输出以下信息,最后一行会提示,通过什么网址可以访问博客.
打开浏览器,将网址粘贴到浏览器即可访问到博客系统.
$hexo serve
INFO Validating config
INFO Start processing
INFO Hexo is running at http://localhost:4000 . Press Ctrl+C to stop.
使用浏览器打开http://localhost:4000
打开博客首页会看到一些默认的博客页面,后面我们将会讲解如何修改代码来构建自己的博客系统.
6. 创建第一篇博文
将一篇 markdown 格式的文章拷贝到 source 目录下,在博文开头加上标题,日期,标签页.
刷新浏览器,即可看到自己的第一篇博客文章.
创建一篇博文, 向世界宣布你来了.
---
title: 使用Hexo搭建自己的博客网站
date: 2021/10/4
tags:
- Hexo
categories:
- blog
---
## first blog
hello world!
7. 如何发布博客
7.1. 创建 github 代码仓库
创建一个以你的 github 用户名命名的代码仓库例如 xxxx.github.io,
7.2. 安装 deployer 插件并配置 deploy
安装 hexo-git plugin
npm install hexo-deployer-git --save
或者
cnpm install hexo-deployer-git --save //推荐
修改配置文件_config.yml 配置 deploy
# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
- type: git
repo: git@github.com:your_github_id/xxxx.github.io.git
branch: gh-pages
name: yourname
email: your_email@xxx.com
说明: 这里的 url 可以是 http https 也可以是 git url 但是建议使用 git url
实测在 push 文件到 github 时使用 https 路径,经常会有异常抛出,使用 git url 后比较稳定
使用 https url 需要在 url 上添加授权方式和 token 像这样 repository: https://oauth2:your_token@github.com/*****.github.io, 实测可行 on Nov 1 2021
为了防止将一些非必要的文件推送到 github 仓库,创建一个.gitignore 文件, 内容如下:
.DS_Store
Thumbs.db
db.json
*.log
node_modules/
public/
.deploy*/
7.3. 创建 gitHub token
打开自己的 GitHub 主页,点击自己的头像找到 Settings 并进入, 选择 developer settings 在左边目录栏找到 Personal access tokens,点击 Generate new token,按照步骤申请即可,过程比较简单, 这里不详述。
Scopes(范围)只需要授权 repo:status 和 repo:public_repo 权限即可 。Token 申请成功后,将 Token 复制并保存起来.当运行发布命令时需要输入此 token 作为密码
这样前期准备工作基本完成,现在开始发布博客。
发布博客系统使用如下命令:
hexo clean && hexo generate && hexo deploy
当提示输入 git 用户名密码时,输入你的 github 用户名, 当提升输入密码时,输入上面生成的 token
7.4. 验证发布是否成功
浏览器打开自己的博客首页 https://xxxx.github.io/
由于我设置了 dns cname 所以实际会跳转到https://pengtech.net/
回头看一下 hexo 上传了哪些文件到 github, 其实只是上传了编译后的文件
所以需要自己将源文件保存到一个私有仓库,或者上传到另一个 github 仓库
2021/10/04/post
archives
css
fancybox
js
tags/Hexo
index.html
8. 选择一个漂亮的主题
可以参考我的文章,里面有 10 多款精美的主题可供选择16 款精美的 hexo 博客主题推荐 | 鹏叔的技术博客
9. 进阶: 如何开启评论, 转发, 优化界面等等
可以参考我的文章 Hexo 博客添加评论功能 | 鹏叔的技术博客
更多 Hexo 相关主题可以访问我的博客 hexo 主题https://pengtech.net/hexo/
10. 插入图片
Markdown 并不会保存插入的图片资源本身,只是记录了获取资源的链接。因此我们需要选择一款合适的图床来支持博客写作,目前各大云服务商都提供了对象存储服务,如七牛云 KODO、又拍云 USS、腾讯云 COS、阿里云 OSS 等。
可以使用PicGo工具上传图片到图床上。
11. 进阶: SEO 优化
可以参考我的文章 Hexo 博客搜索引擎优化| 鹏叔的技术博客
12. 文章置顶
这一功能已被加入 hexo-generator-index。之前老的方法使用 hexo-generator-index-pin-top 替换 hexo-generator-index, 这种不要再参考了, pin-top 已经八年没有更新了. 详细使用方法可以参考 hexo-generator-indexed
在文章的 Front-matter 中增加一个 sticky 参数用来置顶,其值应为大于 0 的整数,表示置顶的优先级(未指定则默认为 0)。数字越大,文章越靠前。
---
title: example
sticky: 100
---
13. 相关阅读
14. 参考文档
15. trouble shooting
-
问题: 启动时遇到 err: Error: ENOSPC: System limit for number of file watchers reached
具体错误信息如下
$hexo server INFO Validating config INFO Start processing FATAL { err: Error: ENOSPC: System limit for number of file watchers reached, watch '$your_project_dir/blog/source/' at FSWatcher.<computed> (internal/fs/watchers.js:218:26) at Object.watch (fs.js:1582:34) at createFsWatchInstance ($your_project_dir/blog/node_modules/chokidar/lib/nodefs-handler.js:119:15) at setFsWatchListener ($your_project_dir/blog/node_modules/chokidar/lib/nodefs-handler.js:166:15) at NodeFsHandler._watchWithNodeFs ($your_project_dir/blog/node_modules/chokidar/lib/nodefs-handler.js:331:14) at NodeFsHandler._handleDir ($your_project_dir/blog/node_modules/chokidar/lib/nodefs-handler.js:559:19) at processTicksAndRejections (internal/process/task_queues.js:95:5) at async NodeFsHandler._addToNodeFs ($your_project_dir/blog/node_modules/chokidar/lib/nodefs-handler.js:609:16) at async $your_project_dir/blog/node_modules/chokidar/index.js:451:21 at async Promise.all (index 0) { errno: -28, syscall: 'watch', code: 'ENOSPC', path: '$your_project_dir/blog/source/', filename: '$your_project_dir/blog/source/' } } Something's wrong. Maybe you can find the solution here: %s https://hexo.io/docs/troubleshooting.html
解决办法
扩大能 watch 的文件数上限
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
-
问题: The TLS connection was non-properly
fatal: unable to access 'https://github.com/xxxx/xxxx.github.io/': gnutls_handshake() failed: The TLS connection was non-properly terminated. FATAL { err: Error: Spawn failed at ChildProcess.<anonymous> ($your_project_dir/blog/node_modules/_hexo-util@2.5.0@hexo-util/lib/spawn.js:51:21) at ChildProcess.emit (events.js:400:28) at Process.ChildProcess._handle.onexit (internal/child_process.js:277:12) { code: 128 } } Something's wrong. Maybe you can find the solution here: %s https://hexo.io/docs/troubleshooting.html
原因分析
其实出现这个问题,很大可能是因为 https 和 http 的 proxy 的对应的分别是 https 和 http 开头的 proxy server,而 https 的 proxy server 可能无法正常工作。一个 workaround 是把 https 的 proxy server 换成 http 的 proxy server:
解决办法
解决办法有三种,
修改_config.yml 文件的 deploy 部分,将 https 修改为 http url 或者 设置为 git url, 配置为 https oauth2 加 token- 设置为 git url(推荐)
deploy: type: git repo: git@github.com:your_github_id/your_github_id.github.io.git branch: gh-pages
这里建议配置为 git url
- 将 https 修改为 http url
deploy: type: git repo: git@github.com:your_github_id/your_github_id.github.io.git branch: gh-pages
- 在 repo https url 上要添加授权方式和 token
deploy: type: git repo: https://oauth2:your_github_token@github.com/your_github_id/your_github_id.github.io.git branch: gh-pages
-
问题: 站内链接跳转不灵
-
现象:
当时使用 markdown 标准的站内跳转链接写法时,再发布后发现链接是错的跳转不过去,例如
[如何创建一个 nodejs 模块](how_to_create_a_node_module.md)
-
原因分析: 生成的链接是不对的,路径上缺少了年月等信息
-
解决办法
替换为下面这种写法,就能正确跳转
{% post_link nodejs/how_to_create_a_node_module %}
更多详细分析可以参考知乎上的这篇文章
- 链接包含中文不能正常跳转问题
-
现象:当右侧大纲条目中包括中文时,点击不能正确跳转
打开浏览器开发者模式发现以下错误utils.js:240 Uncaught TypeError: Cannot read property 'getBoundingClientRect' of null at HTMLAnchorElement.<anonymous> (utils.js:240)
-
原因分析:
中文链接在转码后不能正确的映射到相应的页面元素
-
解决方案
我已经通过此issue反馈给 hexo 社区,社区的回复是在新的 Next theme 中已经解决此问题,需要升级 next theme 到新版本, 以下是来自社区的回复:
This issue has been fixed in next-theme/hexo-theme-next@0d2b3af Theme NexT version 7.8.0 is outdated. The latest version is v8.8.0 https://github.com/next-theme/hexo-theme-next/releases/tag/v8.8.0
16. 相关阅读
posted on 2024-08-17 15:37 eagle.supper 阅读(133) 评论(0) 编辑 收藏 举报