博客搭建

使用github pages 搭建个人博客

参考案例：

https://blog.csdn.net/yaorongke/article/details/119089190

问题：

  1. 如何快速构建一个功能完整的个人博客？
  2. 如何管理博客(增删改查)？
  3. 如何使用风格主题？
  4. 如何添加用户评论？

如何快速构建一个功能完整的个人博客？

创建一个 github page

准备：

  1. 一个github账号
  2. 一个github的ssh公钥
  3. 安装好的git

技术基础：

  1. html
  2. git

在 github创建一个仓库，仓库名应该遵循<username>.github.io的命名规范。

在本地找个文件夹作为Blog仓库，在这里创建一个index.html作为欢迎页

1
2
3
4
5
6
7
8
9
10
<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>Halofu's Blog</title>
</head>
<body>
<h1>欢迎到 Halofu's Blog</h1>
</body>
</html>

然后初始化仓库、提交和push

1
2
3
4
5
6
git init
git add .
git commit -m "添加index.html"
git add blog_github git@github.com:halofu/halofu.github.io.git
# 如果没有添加公钥，这里会push失败。我这里的本地分支为master，这个以自己的分支为主。
git push blog_github master

不出意外，这个时候访问：https://<username>.github.io/ 便可以访问到 index.html的内容。至此，完成了一个最简单 github pages。

添加Hexo框架

介绍：Hexo，方便部署和管理博客。

准备： 需要事先安装 node.js，配置好环境变量，这里不做补充。

流程简述

1
2
3
4
5
npm install hexo-cli -g
hexo init blog
cd blog
npm install
vim _config.yml
1
2
3
4
5
# post_asset_folder 已经存在，找到了后修改值即可
post_asset_folder: true
marked:  
  prependRoot: true
  postAsset: true
1
2
npm install hexo-asset-img
hexo generate   # 这一步不要省略了，用于生成静态文件，可以写成 hexo g

新开一个窗口，执行命令：

1
hexo server

再开一个窗口来创建文章

1
hexo new post 测试文档

进入source/_post，用typora打开测试文档.md，修改全局图像插入配置。

  1. 第一个下拉框选择“复制到指定路径”
  2. 然后在框内输入./${filename}

测试效果：

  1. 复制一张图片到测试文档.md，此时图片会自动存入到文件夹测试文档。
  2. 关闭server，然后hexo clean && hexo g && hexo s
  3. 此时打开首页，进入文章《测试文档》，可以看到图片正常显示。
  4. 将鼠标移至图片上，图片资源路径为”http://localhost:4000/2025/4/13/测试文档/test.jpg“ 。路径正常，并没有存到其他位置。

安装 Hexo

首先是安装Hexo，这个照着官网首页的操作即可

1
2
3
4
5
6
npm install hexo-cli -g
hexo init blog
cd blog
npm install
hexo generate      # 这一步不要省略了，用于生成静态文件，可以写成 hexo g
hexo server        # 启动服务,可以写成 hexo s

服务启动后，访问本地服务页：http://llocalhost:4000 即可看到 Hexo成功启动的欢迎页

Hexo官方文档

基础命令介绍

一、从Hexo创建新文章/新页面：

1
hexo new [layout] <title>

layout 是布局，默认为post，命令结束会在默认资源路径(source/_posts)下创建一个文件名为标题名的md文件。

layout官方说明：

Hexo 有三种默认布局：post、page 和 draft。 每个布局创建的文件会被保存到不同的路径。 新创建的帖子被保存到 source/_post 文件夹。

布局 路径
post source/_posts
page source
draft source/_drafts

如果只是将其他md复制过来，虽然可以在服务上显示，但会缺少标题。

官方说明：

默认情况下，Hexo 使用帖子标题作为其文件名。 您可以编辑 _config.yml 中的 new_post_name 设置去更改默认文件名。 例如， :year-:month-:day-:title.md 将在文件名前加上创建日期。 你可以使用以下占位符：

占位符 描述
:title 标题（小写，空格将会被替换为短杠）
:year 建立的年份，比如， 2015
:month 建立的月份（有前导零），比如， 04
:i_month 建立的月份（无前导零），比如， 4
:day 建立的日期（有前导零），比如， 07
:i_day 建立的日期（无前导零），比如， 7

使用new命令来新建文档，比较适合从头开始编写的文档，如果已经有写好的内容，这种方式不合适。而直接将md文件复制到_posts文件夹下，还需要对文件头进行修改，不太方便。

二、草稿

命令：hexo publish [layout] <title>

使用草稿，可以仔细审核好后再发布。

1
2
hexo new draft <title> # 创建草稿，存于source/_drafts目录
hexo publish draft <title> # 发布草稿，存于source/_posts目录

三、脚手架

在新建文章时，Hexo 会根据 scaffolds 文件夹内相对应的文件来建立文件。

命令：

1
hexo new [layout] <title>

默认scaffolds下有三个模板：post、page 和 draft。如果需要新的脚手架， 可以在这里新建，使用的时候将自定义的脚手架文件名作为layout即可。

修改配置

了解了必要的基础命令后，修改根目录下的_config.yml，修改并添加如下内容

1
2
3
4
5
# post_asset_folder 已经存在，找到了后修改值即可
post_asset_folder: true
marked:  
  prependRoot: true
  postAsset: true

开启post_asset_folder，可以让md的图片等资源保存到同一文件名目录下。

开启marked这两个配置，可以自动对markdown的图片引用语法做映射

插件安装

一般都是通过 npm下载插件，需要注意的是命令使用时当前的目录位置，要再hexo 初始化的blog根目录下。

例子：
这是经过hexo init过的目录：

1
2
3
4
5
6
7
blog_hexo
	/node_modules
	/scaffolds
	/source
	/themes
	...
	package.json

看到这个package.json没，就在这个blog_hexo目录下安装。安装成功后，package.json会有对应的依赖。依赖添加上了，就算插件安装成功了。

1
2
cd blog_hexo
npm install hexo-asset-img # 为当前目录安装插件

hexo-asset-img 这个插件解决的是 typora 里图片路径与 hexo 图片路径的一个映射问题。

具体来说：

Hexo 在没有这个插件之前，开启了前面的 marked 配置，会存在一个问题。也就是你的图片要是想在Hexo显示，则在typora里就需要将当前文件设置为根目录。这点不友好，也容易出现错误，所以就需要这个插件做一个路径映射。有了这个插件之后，在两个地方都可以正常显示图片。

安装hexo-deployer-git

1
npm install hexo-deployer-git

编辑文件_config.yml，修改如下内容：

1
2
3
4
5
deploy:
  type: git
  repo: git@github.com:halofu/halofu.github.io.git
  branch: master
#  message: [message]

博客一键部署

1
hexo clean && hexo d

问题

下面是我之前遇到的问题，没遇到直接跳过

在插件安装之后，如果没有正常显示，多试试hexo clean和hexo g。我也没总结出规律来，但是如果以上配置都做好了，还有图片路径映射问题，就多试试清除本地静态资源并重新生成。我在第一次会出现问题，第二次就好了，暂时没心思去调试，抽空再搞搞。

而且，这个markdown渲染插件hexo-renderer-marked也有点问题，有的时候会无法完成资源图片解析。

这个问题找到原因了：
我的yaml文件在配置marked的时候，prependRoot:true 这里，true后面有空格！导致格式不规范，就会造成这个属性非true，成了false。所以没有进行解析。
其次，在更新了yaml文件后，建议重新生成一次静态资源，刷新页面后，就可以看见正常了。
配置_config.yml应该放在generate前面

1
2
3
4
5
npm install hexo-cli -g
hexo init blog
cd blog
npm install
vim _config.yml
1
2
3
4
5
# post_asset_folder 已经存在，找到了后修改值即可
post_asset_folder: true
marked:  
  prependRoot: true
  postAsset: true
1
2
npm install hexo-asset-img
hexo generate --watch    # 这一步不要省略了，用于生成静态文件，可以写成 hexo g -w

新开一个窗口，执行命令：

1
hexo server --debug

再开一个窗口来创建文章

1
hexo new post 测试文档

进入source/_post，用typora打开测试文档.md，修改全局图像插入配置。

  1. 第一个下拉框选择“复制到指定路径”
  2. 然后在框内输入./${filename}

测试效果：

  1. 复制一张图片到测试文档.md，此时图片会自动存入到文件夹测试文档。
  2. 由于事先用watch对资源进行了监听，所以会自动构建到public文件夹下。
  3. 此时打开首页，进入文章《测试文档》，可以看到图片正常显示。
  4. 将鼠标移至图片上，图片资源路径为”http://localhost:4000/2025/4/13/测试文档/test.jpg“ 。路径正常，并没有存到其他位置。我这里没有成功

查看监控日志：

在自动构建的时候，对图片资源的路径构建出现了错误。

原因：打开创建的文档后，复制图片进来导致的问题
解决：

  1. 中断server、generate

  2. hexo clean，紧接着hexo g -w

  3. 最后hexo s --debug

    至此，一个页面的发布的基本需求就都满足了，然后就是部署。

总结，每次部署前，都需要重新clean再生成

存储策略存在问题：

  1. 当使用 hexo g后，public路径下的每个博客的图片都会存储在当日第一篇博客的资源路径下
  2. 只有当日第一篇博客的资源名是完整的，其他博客的资源名就算被转移后，其也会失去完整的资源名（似乎随机残缺）
  3. 只有在当日第一篇博客里，才能使用Hexo的标签语法来读取图片，当日其他博客不行

应对策略：

清空资源，重新生成，这个可以解决问题1和问题2

1
2
hexo clean
hexo g

如何管理博客？

增加博客

1
hexo new [layout] <title>

删除博客

最直接的方式：到对应布局下的文件夹里删除对应的文档和文件夹

1
2
3
cd blog_hexo
cd source/_post
rm -rf <title_dir> <title>.md

修改文章

进入到自己发布的文档里，直接修改

1
2
3
cd blog_hexo
cd source/_post
vim <title>.md

查找文章

到_config.yml里增加文章的关键字，这个可以让你的博客搜索栏里找到你的文章。还没深入了解，暂定。

可视化

构建可视化管理页面（要求版本大于Hexo 3.x）

安装hexo-admin，然后启动服务

1
2
npm install hexo-admin --save
hexo s

进入http://localhost:4000/admin/#/settings，点击Setup authentification here.在这里填写用户、密码、Secret。

系统采用的是bcrypt加密，Secret就是一段自定义的字符数据，用于加密cookies，确保Secret又长又晦涩。

可以在这里快速创建文档和编辑，这里默认只支持font-matter的tags、archive，需要其他的metadata，可以在_config.yml手动添加。

1
2
3
4
5
metadata:
  author_id: defaultAuthorId
  language:
  math: true
  comment:

使用风格主题

首先，Hexo 官网里提供了大量用户提交的主题。可以进入挑选自己喜欢的下来。

1
2
cd blog_hexo
touch _config.<theme>.yml

覆盖配置：

​ 可以使主题配置放置在 fluid 目录之外，避免在更新主题时丢失自定义的配置。支持Hexo 5.0.0 版本以上。将主题的 _config.yml全部配置（或部分配置）复制过去。

注意：

  • hexo 先加载_config.yml，然后才会用 _config.<theme>.yml 覆盖。
  • 只要存在于 _config.<theme>.yml 的配置都是高优先级，修改对应原 _config.yml的配置是无效的。
  • 每次更新主题可能存在配置变更，请注意更新说明，可能需要手动对 _config.<theme>.yml 同步修改。
  • 想查看覆盖配置有没有生效，可以通过 hexo g --debug 查看命令行输出。
  • 如果想将某些配置覆盖为空，注意不要把 _config.<theme>.yml下对应的配置主键删掉/注释，不然是无法覆盖的，比如：
1
2
3
4
about:
  icons:  # 不要把 icon 注释掉，否则无法覆盖配置
    # - { class: 'iconfont icon-github-fill', link: 'https://github.com' }
    # - { class: 'iconfont icon-wechat-fill', qrcode: '/img/favicon.png' }

更换主题后，如果出现样式加载异常，重启Hexo前清空缓存

1
hexo cl

主题1：particle

1
2
3
cd blog_hexo/themes
git clone git@github.com:argvchs/hexo-theme-particlex.git particle --depth=1
touch ../_config.particle.yml

编辑_config.yml，修改主题为particlex

1
theme: particlex

补充

配置里，我没有开启Polyfill，其他也是照着做full主题介绍做的

如果按照我的安装方式下来，使用这个主题，其代码块会有一点问题。此时需要手动修改主题的highlight.js

修改内容如下

1
2
3
4
5
6
let language = [...i.classList, ...i.firstChild.classList][0] || "plaintext";
// 增加判断，将"language-shell" => "shell"
if (language.split('-').length === 2){
    language = language.split('-')[1]
}
let highlighted;

然后就可以正常展示了

主题2：NexT

1
2
3
cd blog_hexo/themes
git clone git@github.com:theme-next/hexo-theme-next.git next
touch ../_config.next.yml

编辑_config.yml，修改主题为next

1
theme: next

主题3：Fluid

1
2
3
cd blog_hexo/themes
git clone git@github.com:fluid-dev/hexo-theme-fluid.git fluid
touch ../_config.fluid.yml

编辑_config.yml，修改主题为fluid

1
theme: fluid

默认样式：https://hexo.fluid-dev.com/posts/hello-fluid/

将 fluid下的_config.yml复制到_config.fluid.yml中

fluid 主题下的 font-matter属性：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
title: 文章标题
# 副标题
subtitle: 若不填默认是 title
date: 2019-10-10 10:00:00
# tags 两种写法，一个列表，一个是markdown的序列语法
tags: [Hexo, Fluid]
# 开启归档
archive: true
# 数值越大，该文章越靠前，post_sticky可以配置置顶图标
sticky: 100
# 指定文章略缩图，在首页展示
index_img: /img/example.jpg
# 置定文章详情页的顶部大图
banner_img: /img/post_banner.jpg
# 开启数学公式渲染，默认的hexo-renderer-marked不支持复杂公式，需要更换渲染器hexo-renderer-pandoc
math: true
# 控制是否开启评论，或者指定评论插件
comment: bool/type
# 摘要
excerpt: 摘要内容

由于主题是手动从github下载下来的，所以需要自己清理掉一些不用的文件，比如.git之类

开启评论功能

Gitalk

首先，您需要选择一个公开github存储库（已存在或创建一个新的github存储库）用于存储评论。

然后需要创建 GitHub Application，如果没有 点击这里申请

homepage url可以填插件的gitalk的仓库url

Authorization callback URL 填写回调url。

  • 如果你是在本地测试，地址可以填：http://localhost:4000
  • 如果你是部署在github page，地址填：https://<username>.github.io
  • 如果你是部署在自己的云服务器，地址填：https://<your domain>:<port>，如果没有ssl证书就用http协议

注册好之后，根据_config.fluid.yml里对gitalk的配置要求填上即可。clientSecret需要到刚创建的OAuth APP里手动生成。

如果出现在授权gitalk后出现403错误，参考解决方案

如果出现重定向错误，仔细检查自己的配置，可以参考我的配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
gitalk:
  clientID: <clientID>
  clientSecret: <clientSecret>
  repo: <仓库名>
  owner: halofu
  admin: ['halofu']
  language: zh-CN
  labels: ['Gitalk']
  perPage: 10
  pagerDirection: last
  distractionFreeMode: false
  createIssueManually: true
  prpxy: https://shielded-brushlands-08810.herokuapp.com/https://github.com/login/oauth/access_token

缺点：

  • 需要手动对每个文章的 Issues 进行初始化
  • 需要设置好代理
  • 相应有点慢

优点：免费

valine

选国际版的leancloud来注册，只需要验证邮箱就好了。创建好应用，将AppID、AppKey获取到配置文件即可。

部署在本地会出现跨域问题，放到github page就好了

​

#Blog
博客搭建
https://halofu.github.io/2025/04/13/博客搭建/
作者
风鸣迎雪
发布于
2025年4月13日
更新于
2025年4月20日
许可协议