hexo+github搭建博客笔记

1. 软件安装和使用

1.Git

查看是否成功安装

1
git version

绑定git邮箱和git用户，命令如下：

1
2
git config --global user.name dkyou #输入git不需要双引号
git config --global user.email 2323@xx.com

2.安装NodeJS

2.1 NodeJS 是一个基于 Chrome V8 引擎的 JavaScript 运行环境。Node.js 使用了一个事件驱动、非阻塞式 I/O 的模型，使其轻量又高效。

简单的说 Node.js 就是运行在服务端的 JavaScript，利用JavaScript在服务端进行编程。

关于NodeJS是什么可以参考：nodejs(第一篇)：nodejs是什么？

2.2 安装并配置环境变量，可以参考：[Node.js安装及环境配置超详细教程](Node.js安装及环境配置超详细教程[Windows系统]_windows 安装nodejs-CSDN博客)

2025年11月1日补充参考链接，可优先参考：2024最新版Node.js下载安装及环境配置教程【保姆级】_nodejs下载-CSDN博客

2.3 同样的，使用命令查看是否安装成功

1
2
node -v
npm -v

3.Hexo安装和设置

3.1 hexo安装命令

1
2
npm install -g hexo-cli
#用于全局安装 Hexo 的命令行工具

以下是上述命令的解释：

1
2
3
4
5
6
7
8
1.npm
npm 是 Node.js 包管理器（Node Package Manager）的缩写，用于管理和安装 Node.js 应用程序的依赖包。
2.install
install 是 npm 的一个子命令，用于安装指定的包。
3. -g
-g 表示全局安装（global）。这意味着包将被安装到系统的全局位置，而不是项目的本地 node_modules 目录中。全局安装的包可以在系统中的任何位置使用。
hexo-cli
4. hexo-cli 是 Hexo 的命令行接口工具。Hexo 是一个静态站点生成器，可以用来快速生成静态博客或网站。

3.2 新建一个文件夹，例如”D:\myblog”，不需要进入该文件夹，直接鼠标右键—>Git Bash Here，依次执行以下命令

初始化myblog,即从https://github.com/hexojs/hexo-starter.git克隆文件，并且安装依赖

1
2
hexo init myBlog

进入myblog文件夹，并且执行npm install命令

1
2
cd myBlog
npm install

运行hexo s命令

1
hexo s

根据提示，可以直接在浏览器中输入http://localhost:4000/,回车即可看到效果

这是部署在本地的默认的一篇hello world博客，使用的是默认theme: landscape主题，此时和github还没有任何关系。

补充工作

  1. Stellar 1.33.1版本的脚本依赖probe-image-size（可选）
1
npm i probe-image-size --save
  1. hexo d依赖hexo-deployer-git工具
1
npm i hexo-deployer-git --save

否则出现以下报错

1
2
3
4
5
6
7
8
$ hexo d
INFO  Validating config
INFO  ------------------------------------------------
INFO  Welcome to Stellar 1.33.1
DOCS  https://xaoxuu.com/wiki/stellar/
REPO  https://github.com/xaoxuu/hexo-theme-stellar.git
INFO  ------------------------------------------------
ERROR Deployer not found: git

2. 主题安装

可从主题官网下载自己喜欢的主题：Themes | Hexo

以hexo-theme-Chic为例设置自己的主题,链接：https://github.com/Siricee/hexo-theme-Chic.git

执行git clone https://github.com/Siricee/hexo-theme-Chic.git或者直接download zip将下载的主题文件解压放在D:\myblog\themes文件夹中。注意文件名为hexo-theme-Chic后边没有-master和其他信息。

在D:\myblog中找到_config.yml，使用记事本或者vscode等打开，在第100行左右找到theme: landscape，改为theme: hexo-theme-Chic。

注意：这里的_config.yml是根目录下的，即”D:\myblog\_config.yml”，不是D:\myblog\themes\hexo-theme-Chic下的_config.yml

image-20240920181648998

依次执行以下命令

1
2
hexo g
hexo s

image-20240920184319727

根据提示，可以直接在浏览器中输入http://localhost:4000/,回车即可看到更换主题之后的效果

image-20240920184229783

themes主题文件结构：

1
2
3
4
5
6
.
├── _config.yml
├── languages
├── layout
├── scripts
└── source

主题配置文件设置：D:\myblog\themes\hexo-theme-Chic下的_config.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
#文件位置`D:\myblog\themes\hexo-theme-Chic`下的`_config.yml`
# Header  
navname: dku's Blog //对应左上角
# 对应右上角  Posts Categories Tags About
# navigatior items
nav:
  Posts: /archives
  Categories: /category
  Tags: /tag
  About: /about

# favicon 浏览器网址栏显示的图标，但是不知道为什么我默认的不是favicon.ico，而是我之前设置的神里凌华的图片，有点奇怪
favicon: /favicon.ico

# Profile 中间显示的名字
nickname: Dku

### this variable is MarkDown form.
# 个人描述 显示在图像下边
description: Lorem ipsum dolor sit amet, **consectetur adipiscing elit.** <br>Fusce eget urna vitae velit *eleifend interdum at ac* nisi.
# 个人头像图片
avatar: /image/avatar.jpeg

# main menu navigation
## links key words should not be changed.
## Complete url after key words.
## Unused key can be commented out.
#常用网站的个人链接，取消注释添加即可
links:
  Blog: /archives
  # Category:
  # Tags: 
  # Link:
  # Resume:
  # Publish:
  # Trophy:
  # Gallery:
  # RSS:
  # AliPay:
  ZhiHu: https://www.zhihu.com/people/sirice
  # LinkedIn:
  # FaceBook:
  # Twitter:
  # Skype:
  # CodeSandBox:
  # CodePen:
  # Sketch:
  # Gitlab:
  # Dribbble:
  Instagram:
  Reddit:
  # YouTube:
  # QQ:
  # Weibo:
  # WeChat:
  Github: https://github.com/Siricee

# how links show: you have 2 choice--text or icon.
# 图标或者文字显示常用网站的个人链接
links_text_enable: false
links_icon_enable: true

# Post page
## Post_meta
post_meta_enable: true

post_author_enable: true
post_date_enable: true
post_category_enable: true
## Post copyright
post_copyright_enable: true

post_copyright_author_enable: true
post_copyright_permalink_enable: true
post_copyright_license_enable: true
post_copyright_license_text: Copyright (c) 2019 <a href="http://creativecommons.org/licenses/by-nc/4.0/">CC-BY-NC-4.0</a> LICENSE
post_copyright_slogan_enable: true
post_copyright_slogan_text: Do you believe in <strong>DESTINY</strong>?
## toc
post_toc_enable: true

# Page
page_title_enable: true

# Date / Time format
## Hexo uses Moment.js to parse and display date
## You can customize the date format as defined in
## http://momentjs.com/docs/#/displaying/format/
#日期格式
date_format: MMMM D, YYYY
time_format: H:mm:ss

# stylesheets loaded in the <head>
stylesheets:
  - /css/style.css

# scripts loaded in the end of the body
scripts:
  - /js/script.js
  - /js/tocbot.min.js
    # tscanlin/tocbot: Build a table of contents from headings in an HTML document.
    # https://github.com/tscanlin/tocbot


# plugin functions
## Mathjax: Math Formula Support
## https://www.mathjax.org
mathjax:
  enable: true
  import: demand # global or demand
  ## global: all pages will load mathjax,this will degrade performance and some grammers may be parsed wrong.
  ## demand: Recommend option,if your post need fomula, you can declare 'mathjax: true' in Front-matter

更改完D:\myblog\themes\hexo-theme-Chic下的_config.yml配置文件之后，可以依次执行hexo g hexo s根据提示，在浏览器中输入http://localhost:4000/,回车即可看到设置主题之后的效果

image-20240920193126322

可以设置的东西挺多，简单设置的效果

补充工作

安装主题可以通过两种方式进行，以我现在使用的Stellar 1.33.1为例

  1. 通过npm方式安装

    • 安装和更新均执行npm i hexo-theme-stellar
    • 在 blog/_config.yml 文件中找到并修改
    1
    theme: stellar

  2. 源码方式安装

通过npm方式安装非常简单，但是对于通过在theme文件夹下新增源代码的方式，需要多做一步操作。

  • 把 Stellar 主题仓库添加为博客仓库的子模块，这里我fork了作者的仓库

    1
    git submodule add https://github.com/dkyou/hexo-theme-stellar.git themes/stellar

  • 复制themes\hexo-theme-stellar\_config.yml到根目录，并重命名为_config.stellar.yml

说明：两个配置文件应该都要设置，并且根目录下的_config.stellar.yml优先级大于主题文件夹下的配置文件

  • 在 blog/_config.yml 文件中找到并修改：

    1
    theme: hexo-theme-stellar

3.将hexo博客部署到github上

以上，所有的设置和内容都只能显示在自己的电脑上，如何部署到github上？

3.1 准备工作—新建仓库并设置ssh key

如果之前已经使用hexo搭建过博客，或者设置过以下内容，则无需再进行设置！
如果想了解什么是ssh key及其原理，可以参考ssh_key简记，本文只讲如何操作。

新建一个github仓库，仓库名要按照：用户名.github.io设置

配置ssh key,使用git配置ssh key，命令如下

1
2
3
git config --global user.name dkyou #输入git不需要双引号
git config --global user.email 2323@xx.com
ssh-keygen -t rsa -C 2323@xx.com

查看ssh

1
cat ~/.ssh/id_rsa.pub

添加可信列表。若返回 Hi xxx! You’ve successfully authenticated, but GitHub does not provide shell access. 内容，则证实添加成功。

1
ssh -T git@github.com

image-20240920194849457

登陆 Github 上添加刚刚生成的SSH key，按如下步骤添加，右上角点击头像-> settings -> SSH and GPG keys，建立一个新的 SSH key, 标题随便，key 就填刚才生成那个，确认建立，这样在你的 SSH keys 列表里就会看到你刚刚添加的密钥。

image-20240920194441963

3.2 部署

在D:\myblog中找到_config.yml，使用记事本或者vscode等打开，找到最后几行，改为

1
2
3
4
5
6
# 文件路径：D:\myblog\_config.yml

deploy:
  type: 'git'
  repo: https://github.com/dkyou/dkyou.github.io
  branch: master

安装 hexo-deployer-git

1
npm install hexo-deployer-git --save

image-20240920195602908

执行命令上传

1
2
hexo g #生成
hexo d #上传

有时候在执行hexo d会报错，再执行一次就可以

image-20240920195816917

成功的截图

image-20240920195932499

接下来使用用户名.github.io即可访问部署到github上的博客

成功部署到github效果演示

image-20240920200418549

image-20240920200638025

4.更新文章

可以使用hexo new '文章标题'命令来创建一个文章标题.md文件，也可以按照格式直接将自己的.md

文件复制到"D:\myblog\source\_posts\"文件夹中，同时按照以下格式添加一些命令

使用hexo new '文章标题'命令来创建一个文章标题.md文件

1
hexo new '文章标题'

博客语法结构:

1
2
3
4
5
6
---
title: Hello World #文章标题
date: 2024-09-20 20:13:20
tags: [tag1,tag2,...]
categories: 
---

将新文章部署到github上

1
2
3
hexo g # 生成，必须
hexo s # 本地渲染，非必要
hexo d # 部署到Github 上，必须

注意：一个主题可能有以下文件结构

1
2
3
4
5
6
.
├── _config.yml
├── languages
├── layout
├── scripts
└── source

涉及到hexo d的文件

Source 文件夹。 将您的素材（如 CSS 和 JavaScript 文件）放在这里。 文件或文件夹开头名称为 _（下划线）或隐藏的文件会被忽略。

Hexo 将处理所有可渲染的文件，并将它们保存到 public 文件夹下。 不可渲染的文件将直接复制到 public 文件夹。

hexo d也会把D:\myblog\source_posts中的md文件上传到 public 文件夹下，如果_post的md文件被删除或者增加，则会完全覆盖github中的md文件，所以不要轻易删除_post文件夹下的md文件。

5.博客备份

为了方便换电脑的时候移植笔记，我将笔记通过 GitHub 托管源代码。同时将主题作为仓库子模块。

克隆项目：

1
2
3
git clone git@github.com:dkyou/blog-source.git
cd blog-source
git submodule update --init --recursive

安装 Hexo 环境：

1
2
npm install hexo-cli -g
npm install

安装deployer

1
npm i hexo-deployer-git --save

确认 _config.yml 里部署设置（SSH 模式）

测试：

1
hexo g && hexo s

打开 http://localhost:4000 看是否正常

部署：

1
hexo d

之后对主题的修改都在 themes/hexo-theme-stellar 里做：

1
2
3
4
5
6
7
8
9
10
cd themes/hexo-theme-stellar
# 修改文件...
git add .
git commit -m "xxx"
git push -u origin main
cd -
# 回到主仓库，提交“子模块指针”的变更
git add themes/hexo-theme-stellar
git commit -m "xxx"
git push

6.拉取原仓库

问题描述：

在fork完原 https://github.com/xaoxuu/hexo-theme-stellar.git仓库为自身仓库it@github.com:dkyou/hexo-theme-stellar.git之后，修改并推送了_config.yml文件。现在想要新建main-dky分支用于保存自己的修改，main分支用于跟踪原仓库更新，再合并/变基进main-dky。注意以后不要在main分支上写代码。

  • upstream → 原作者的仓库（xaoxuu/hexo-theme-stellar）
  • origin → 自己的 fork（dkyou/hexo-theme-stellar）

本地有两个分支：

  • main：只用来同步上游，不做改动；
  • main-dky：你自己的开发分支，用来改配置文件、主题样式等。

整理历史

添加 upstream（只需一次）

1
2
git remote add upstream https://github.com/xaoxuu/hexo-theme-stellar.git
git fetch upstream

把当前 main 上的个人改动“搬家”到新分支，做个备份

1
2
git checkout -b main-dky
git push -u origin main-dky   # 备份到你的 fork

把 main 重置为上游（保持 main 干净镜像 upstream）

1
2
3
4
git checkout main
# 如果不确定上游默认分支名，先看一下（通常是 main）：
git remote show upstream      # 会显示 "HEAD branch: main"
git reset --hard upstream/main

覆盖 fork 的 main（需要强推）

1
git push -f origin main

同步和更新

同步上游 → main

1
2
3
4
5
git checkout main
# --ff-only (fast-forward)参数快进方式更新本地main
git pull --ff-only upstream main
# 本地更新后的 main 推送回自己在 GitHub 上的 fork（origin）
git push origin main

把上游更新带到自己开发分支

1
2
3
4
5
git checkout main-dky
# 把刚才同步到 main 的上游更新合并进 main-dky
git merge main      # 或：git rebase main（更线性）
# 更新后的 main-dky 推回你的远程仓库（origin/main-dky）
git push origin main-dky
  1. 增加一个关于我[about]页

新建source/about/index.md文件
添加以下内容:

1
2
3
4
5
6
7
8
9
10
11
12
13
---
title: About
layout: page
comments: false
---
## 嗨，我是 👋
- 研究方向：
- 正在做的事：

**联系我**
- GitHub：[xxx](https://github.com/xxx)
- 邮箱：you@example.com

其他地方无需更改，编译，生成，上传即可。但是不知道前两天为什么不行，今天突然就可以了。

  1. 增加一个friends和explore页
    对于新增explore来说，只需要新建source/explore/index.md文件，然后添加内容即可。

对于friends来说，除了要新建source/explore/index.md文件外，如果要使用静态友链，需要新建source\_data\links\friends-developer.yml文件，并添加内容。
添加内容可以是：

1
2
3
4
5
6
7
8
9
10
11
# 每条就是一个友链
- title: xxx
  url: https://
  cover:
  icon:
  description: 
- title: xaoxuu
  url: https://xaoxuu.com/
  avatar: 
  description: Stellar 主题作者 · 创意前端开发者

在source/explore/index.md或任意md文档中引用方式如下：

1
{% friends friends-developer %}

完结！

许可协议

本文采用 署名-非商业性使用-相同方式共享 4.0 国际 许可协议，转载请注明出处。