Github Page博客搭建

2023-08-17

Node

字数统计: 7.3k | 阅读时长≈ 27 分钟

前提介绍

知道下面这些的人可直接跳转到：《电脑本地安装：Node.js》或者《电脑本地安装：Hexo》观看。

Git

Git是一个分布式版本控制系统，用来跟踪文件和项目的变化，可以记录文件的修改历史，使多个开发者能够协同工作并管理代码的版本，常用于个人或多人软件开发。就像游戏存档？

GitHub

GitHub是一个基于 Git 的代码托管平台，提供了集中式的远程代码仓库托管服务。开发者可以将他们的代码存储在 GitHub 上，并与其他开发者协作、分享代码以及管理项目。

GitHub Pages

GitHub Pages是 GitHub 提供的静态网页托管服务，允许用户创建和托管静态网站。用户可以通过 GitHub Pages 将自己的代码仓库中的静态文件自动部署为可访问的网站。

Github Page的官方介绍页

Markdown和md文件

MD文件是一种使用纯文本格式编写的标记语言文件，扩展名为.md。MD是Markdown的缩写，Markdown是一种轻量级的标记语言，用于以易读易写的方式编写文档。

可以使用任何文本编辑器，例如记事本、Sublime Text、Visual Studio Code等。只需使用纯文本编写，然后使用Markdown语法来标记文本的格式。一些常用的将MD文件转换为HTML的工具包括Markdown编辑器（例如Typora、Dillinger、StackEdit、Obsidian等）和命令行工具（例如pandoc）。

参考：

Markdown语法说明（中文版）：https://markdown-zh.readthedocs.io/en/latest/

Markdown Guide：https://www.markdownguide.org/

YAML配置文件

YAML是一种人性化的数据序列化语言，适用于所有编程语言，专门为常见用例而创建的，例如：配置文件、日志文件、进程间消息传递、跨语言数据共享、对象持久化和调试复杂数据结构。

YAML 文件使用 .yml 或 .yaml 扩展名，并遵循特定的语法规则。

YAML是一种简单、表达力强的、以数据为导向的语言，它不是一种标记语言 (YAML)，作为配置格式时非常易读。它具有直观的可视化结构，并且其逻辑非常简单：缩进的项目继承父项目的属性。

YAML使用缩进来确定结构并表示嵌套。为了保持跨系统的可移植性，设计时不允许使用制表符，因此改用空格（字面意义的空格字符）

在_config.yml配置文件中：

deploy:
  type: git
  repo: git@github.com:KiraraKira/Kirara.github.io.git
  branch: main

相当于：

1
2
3

deploy.type: git
deploy.repo: git@github.com:KiraraKira/Kirara.github.io.git
deploy.branch: main

有关YXML的教程可以参考：

YAML教程

YAML Ain’t Markup Language (YAML™) version 1.2

YAML 语言教程

YAML for beginners

What is YAML?

YAML Glossary

# YAML教程（快速入门版）

## YAML 入门教程

注册 GitHub 账号

在游览器打开 GitHub 的官方网站。网址：
https://github.com

点击右上角 “Sign up”（注册）按钮，进入注册页面。

下图就是注册页面了。

在注册页面，填写用户名（Username）、电子邮件地址（Email address）和密码（Password）

全部填写完毕后，点击 “Create account”（创建账号）按钮。

根据提示完成其他必要的信息，例如选择计划（免费或付费）、是否开启学生优惠和接受相关条款等等，根据自己的需要选择。

完成注册后，会在邮箱内收到一封确认电子邮件，邮箱内有验证码。

点击邮件中的确认链接和相应验证码，激活GitHub 账号。

电脑本地安装：Git

下载Git

这里是Windows系统下载git的方式。

打开 Git 的官方网站：
https://git-scm.com/download/win

点击左侧的 ”Downloads“（下载）。

根据电脑的系统选择下载32位和64位。

安装Git

双击下载的安装程序文件（通常是一个 .exe 文件），启动 Git 的安装向导。

Git-2.41.0.3-64-bit.exe

根据提示开始下载，通常情况下选择默认即可

但是需要注意的是，有两个务必选择的选项：

“Use Git from the Windows Command Prompt”（在 Windows 命令提示符中使用 Git）
“Checkout Windows-style, commit Unix-style line endings”（检出 Windows 风格，提交 Unix 风格的行尾）

后面的内如果没有特别要改的需求，可以全部按照默认格式

Tips：关于安装的更多详情可参考：超详细之Git 2.41.0版本安装教程

配置Git环境

在之前的git安装中，会默认配置电脑环境变量，如果没有默认配置的话，按照下面的步骤手动配置环境变量：右键点击打开 “此电脑” 或 “我的电脑” ，点击 “属性”

点击右侧的 “高级系统设置”

点击 “环境变量”

找到 “系统变量” 中的 “Path”，双击打开

查看系统环境变量中是否有git安装地址。如果没有，手动点击右侧的“新建”添加。

添加成功后，原路返回的顺序依次点击 “确定”。

确认git安装无误后，来看看git能不能正常使用吧！

打开cmd窗口或桌面上的git图标：

输入：

where git

或

1	git --version

可以查看git安装地址和git版本。

显示了git的版本表示git已经成功安装。

配置用户信息

已经安装好Git后，寻找一个没什么重要文件的文件夹，鼠标右键点击空白处，点击Open Git Bash here，打开git bash。

在命令行中输入以下命令，设置全局的用户名和电子邮件地址。

引号内的内容记得替换为Github账号中实际的用户名和电子邮件地址。

实际的用户名是在注册的时候使用的Username。

1 2	git config --global user.name "Your Name" git config --global user.email "your_email@example.com"

例如：

1 2	git config --global user.name "Kirara" git config --global user.email "kirara@Rhodes.com"

验证Git 配置

使用下面的命令查看自己有没有配置成功名字和邮箱：

1 2	git config user.name git config user.email

第一个命令 git config user.name 用于检索配置的用户名，第二个命令 git config user.email 用于检索配置的邮箱地址。

在命令行或终端中执行这两个命令时，将输出您当前本地 Git 配置中设置的用户名和邮箱地址。

如果输出了之前配置的内容，表示配置成功。

还可以使用：

1	git config --global --list

来查看git的全局配置

配置SSH协议

Github向仓库推送代码时，可以使用 SSH 协议进行推送。

SSH（Secure Shell）是一种网络协议，用于在不安全的网络中安全地进行远程登录和数据传输。它通过对网络连接进行加密和身份验证来保护通信的安全性。

SSH 私钥（Private Key）是一种加密密钥，用于身份验证和加密数据。私钥通常存储在本地计算机上，并且必须保持私密和安全。每个用户都会有自己的私钥。

SSH 公钥（Public Key）是与私钥相关联的公共密钥。它可以安全地与他人共享，而不会泄露私钥的内容。公钥可以用于验证与其对应的私钥，从而实现安全的身份认证和加密通信。

配置SSH协议需要配置相关的私钥和公钥。

生成SSH私钥

生成SSH私钥有很多种方法

例如：在git bash窗口中输入：

1	ssh-keygen -t rsa -C "邮件地址"

或者打开cmd窗口，输入：

1	ssh-keygen -t rsa -C "邮件地址"

上面两条命令生成密钥的命令是RSA（Rivest-Shamir-Adleman）加密算法，默认使用较短的 2048 位。

生成密钥可以任意选择自己想用加密方式，例如，下面的密钥也是使用了算法，但使用-b 4096 参数指定了生成的 RSA 密钥的长度为 4096 位：

1	ssh-keygen -t rsa -b 4096 -C "邮件地址"

除了RSA加密算法以外，还有DSA（Digital Signature Algorithm）等等许多种都可以使用，相关具体的使用方法可以自己在网上查找。

例如：下图中使用的是Ed25519 算法。

1	ssh-keygen -t ed25519 -C "邮件地址"

下图显示密钥已经生成完毕了。

获取 SSH 公钥

在生成 SSH 密钥对后，需要获取公钥的内容。

找到公钥文件生成的位置，打开公钥文件（通常文件默认在 ~/.ssh/id_rsa.pub），使用记事本打开，复制全部内容。

添加 SSH 密钥

登录到你的 GitHub 帐户，点击右上角的头像，点击Settings，也就是设置

在左侧的菜单中，选择选择 “SSH and GPG keys”（SSH 和 GPG 密钥）

点击 “New SSH key”（新建 SSH 密钥）。

添加密钥信息：在 “Title”（标题）字段中，为该 SSH 密钥提供一个描述性的名称，可随意填写。

然后，在 “Key”（密钥）字段中，粘贴之前复制的 SSH 公钥内容。

保存 SSH 密钥：点击 “Add SSH key”（添加 SSH 密钥）按钮，将 SSH 密钥保存到 GitHub 账号中

测试SSH配置

为了确保 SSH 密钥正确配置，确保电脑可以与 GitHub 进行连接，使用下面的命令来验证SSH是否配置成功：

1	ssh -T git@github.com

如果一切设置正确，会收到一条像下面这样的欢迎消息：

1	Hi KiraraKira! You've successfully authenticated, but GitHub does not provide shell access.

电脑本地安装：Node.js

因为Hexo 是一个基于 Node.js 的静态网站生成器，所以需要安装Node.js。

而Node.js 是一个运行时环境，让 JavaScript 可以在服务器端运行。

需要用到Hexo，在安装Hexo之前，还需要先下载安装Node.js。

安装Node.js

访问 Node.js 官方网站：在您的浏览器中打开：(https://nodejs.org/en)

在node.js官网下载安装，和Git一样，基本按照默认配置安装就可以了。

查看npm版本

npm（Node Package Manager）是一个由 Node.js 的包管理器，与 Node.js 一起安装提供。主要功能是允许开发者在 Node.js 环境中查找、安装、更新和管理 JavaScript 包（也称为模块）。

也就是说，安装好Node.js后，理论上会自动安装好npm。

使用下列命令查看 npm 和 Node.js 的安装版本：

1 2	npm -v node -v

可查看版本即为npm安装成功。

如果不显示版本，参考之前的《配置Git环境》：右键点击”此电脑“，点击”属性“，点击”高级系统设置“，点击”环境变量“，在”系统变量“中找到 ”Path“，查看环境变量中是否有 node.js，如果没有，手动找到 node.js 的安装路径，手动将路径添加进Path，并按原路径确认。

电脑本地安装：Hexo

Hexo 是一个基于 Node.js 的静态博客框架，它使用 Markdown 文件来创建和管理内容，并生成静态网页供发布，Hexo 需要依赖 npm 安装。

Hexo 官方文档：https://hexo.io/zh-cn/docs/commands

安装Hexo

在当前项目目录下安装 Hexo 及其相关依赖项：

1	npm install hexo

全局安装 Hexo 的命令行工具（CLI）

使用 npm 在全局范围安装 Hexo 的命令行工具（Hexo CLI），安装好后可以在任何目录下通过命令行使用 Hexo 相关命令，不仅限于特定的项目目录。

1	npm install -g hexo-cli

在全局范围内强制重新安装 Hexo CLI

如果之前下载过Hexo，电脑中已经存在旧版本的 Hexo CLI，默认情况下，为了防止意外覆盖或破坏现有的配置或数据， npm 会而是保留原来的旧版本，不会安装。

但是如果想要强制安装新版本的Hexo，或单纯想要重新安装，可使用 --force 标志，强制 npm 忽略现有的 Hexo ，开始安装全新的Hexo。

这个命令会删除旧版本的 Hexo CLI，并用最新版本进行替换。强制重新安装可以确保Hexo CLI 是最新版。

1	npm install -g hexo-cli --force

查看Hexo版本

下面两个命令都可以显示 Hexo 的版本信息：

1
2
3

hexo -v

hexo -version

如果查看版本时只显示“hexo-cli: 4.3.1”，是正常情况，是因为hexo没有初始化，之后使用 hexo init 文件夹名 初始化后就可以看到 hexo 的版本。

正式创建Github Page

现在，准备好了Github账号，配置好了Git，安装好了Node.js环境和Hexo，可以正式创建Github Page了！

创建Github仓库

点击右上角的加号，选择“New repository”。

Repository（仓库）是用于存储和管理代码项目的地方。

一个 Repository 可以包含项目的所有文件、文件夹、版本历史记录、分支、标签以及与项目相关的其他资源。

在Create a new repository页面，找到：Repository name *。这里的星号表示必填项。

填入新建的仓库名字。

注意：仓库的名字一定要填：

1	博客名字.github.io

不可以省略后面的 github.io ，否则无法建立正确的Github Page。

创建好后，修改一下仓库的配置。

点击 Seetings （设置），进入仓库的设置页。

"Pages"（页面）选项提供了配置和管理项目的静态网页的功能，

如下图所示：默认的分支为：main。

分支名需要记住，后面的网站配置中需要使用。

点击左侧的Pages。

找到：Buile and deployment（构建和部署）

Source（源）：

Github Actions（Github操作）最适合使用框架和自定义构建过程

适合需要灵活性和自定义性的项目，可以根据特定的框架、工具和构建流程来执行自动化任务。
Deploy from a brance（从分支部署）经典页面体验

只有经过验证的代码被部署到生产环境，提供稳定和可靠的页面体验。

两种构建和部署方法都可以支持使用Hexo ，但Hexo 更适合使用 Deploy from a branch 。

例如，可以将 Hexo 生成的静态网页文件所在的分支（通常是 gh-pages 分支，在下图中我使用了默认的的 main 分支）作为部署源。

启用 Deploy from a branch 并选择该分支后，每次推送代码到该分支时，GitHub Pages 会自动构建并部署分支上的静态网页。

初始化Hexo

在电脑容易找到的位置新建一个文件夹，尽量与自己的Github 仓库同名，例如：D:\Kirara\Kirara.github.io

这个文件夹就作为存放代码的地方。

进入文件夹：

1
2
3

cd 文件夹名

cd Kirara.github.io

初始化一个新的 Hexo 网站：

hexo init

Hexo 将创建一个新的文件夹，其中包含用于构建和管理网站的基本文件和目录结构。

_config.yml：Hexo 网站的主要配置文件，包含网站的各种设置选项，如标题、URL、主题等，可以在这个文件中进行自定义配置。

package.json：Node.js 的包管理文件，用于管理 Hexo 网站所需的依赖包和插件，可以使用 npm 或 yarn 命令来安装、更新和管理依赖项。

scaffolds 目录：包含用于生成新文章、页面和草稿的模板文件，在命令行中使用 Hexo 提供的相应命令，可以使用这些模板快速创建新的内容。

source 目录：用于存储 Hexo 网站的源文件，包括 Markdown 格式的文章和页面。您可以在这里编写和管理网站的内容。

themes 目录：用于存放主题文件的目录。Hexo 支持使用不同的主题来定制网站的外观和样式。在此目录中，您可以将下载或自定义的主题放置在相应的子目录中。

安装Hexo的依赖包

运行 npm install 命令，会根据项目中的 package.json 文件中的依赖项列表，将所有所需的软件包和模块下载并安装到当前项目的 node_modules 文件夹中。
这些依赖包通常是项目所需的第三方库、框架、工具或插件。

1	npm install

运行npm install命令后，会自动下载一些依赖文件到Kirara这个目录，下载到node_modules中。

node_modules文件夹内的依赖文件不要轻易删除

安装Hexo需要的插件

Hexo 默认已经包含了下列的渲染引擎插件，大多数情况下不需要手动安装。

但如果在使用 Hexo 过程中遇到了相关的渲染问题或错误，可以尝试使用下面的安装插件命令重新安装。

在本地文件夹中打开git bush，输入命令即可安装插件：

EJS 渲染引擎插件

1	npm install hexo-renderer-ejs --save

安装 Hexo 博客框架中的 EJS 渲染引擎插件，并将其作为项目的依赖保存。
hexo-renderer-ejs 是 Hexo 的一个渲染引擎插件，它用于将 EJS（Embedded JavaScript）模板语言转换为 HTML 页面。EJS 允许在 HTML 页面中嵌入 JavaScript 代码，以实现动态内容的渲染和生成。

Stylus 渲染引擎插件

1	npm install hexo-renderer-stylus --save

命令的作用是安装 Hexo 博客框架中的 Stylus 渲染引擎插件，并将其作为项目的依赖保存。hexo-renderer-stylus 是 Hexo 的一个渲染引擎插件，用于处理 Stylus 样式表语言。

Tips：Stylus 是一种基于缩进的样式表语言，类似于 Sass 和 Less，它提供了更简洁灵活的语法来编写 CSS。

如果希望在 Hexo 项目中使用其他的样式预处理器（如 Sass 或 Less），可以安装对应的渲染引擎插件，并相应地修改 Hexo 配置文件中的样式相关配置。

Marked 渲染引擎插件

1	npm install hexo-renderer-marked --save

安装 Hexo 博客框架中的 Marked 渲染引擎插件，并将其作为项目的依赖保存。hexo-renderer-marked 是 Hexo 的一个渲染引擎插件，用于将 Markdown 文档转换为 HTML 页面。

三个插件同时安装：

1	npm install hexo-server hexo-browsersync hexo-renderer-pug --save

安装服务器、浏览器同步和 Pug 渲染引擎插件

插件解释

服务器插件

1	npm install hexo-server --save

提供了一个本地服务器，可以在开发环境中预览和调试生成的静态页面。安装 hexo-server 插件后，可以使用 hexo server 命令来启动本地服务器，并通过浏览器访问 Hexo 博客的预览页面。

浏览器同步插件

1	npm install hexo-browsersync --save

浏览器同步插件，它基于 BrowserSync 技术，可以在多个浏览器和设备上同步刷新页面。安装 hexo-browsersync 插件后，可以在使用 hexo server 启动的本地服务器上实现浏览器同步，从而在实时编辑博客内容时，各个浏览器会自动更新并显示最新的页面。

渲染引擎插件

1	npm install hexo-renderer-pug --save

渲染引擎插件，用于处理 Pug（以前称为 Jade）模板语言。Pug 是一种简洁而强大的模板语言，它提供了更简洁的语法来编写 HTML 页面。

安装 hexo-renderer-pug 插件后，Hexo 将使用 Pug 渲染引擎来处理包含 Pug 语法的模板文件，并将其转换为最终的 HTML 页面。

生成静态页面

hexo g 和 hexo generate 用于生成静态页面的命令，完全等价的，可以互换使用。
运行 hexo g 或 hexo generate 命令时，Hexo 会根据博客内容和配置，将 Markdown 文件转换为 HTML 页面，并生成相应的静态页面，将页面生成在public文件夹下。

这些静态页面可以用于发布到服务器或托管平台上，以供访问和阅读。
这两个命令的作用相同，只是 hexo g 是 hexo generate 的简写形式，方便用户记忆和使用。
可以根据个人喜好选择使用哪个命令来生成静态页面，效果是一样的。

hexo g

hexo generate

本地运行预览效果

hexo s 和 hexo server 是 Hexo 博客框架中用于启动本地服务器的命令，同样完全等价的，可以互换使用，没有区别。

运行 hexo s 或 hexo server 命令时，Hexo 会启动一个本地服务器，用于在您的计算机上预览和测试生成的静态页面。您可以通过访问指定的本地地址（默认为 http://localhost:4000）来查看您的博客。

1
2
3

hexo s

hexo server

看到这样的默认页面就代表本地配置成功。

关闭本地运行

键盘同时按下：Ctrl 和C

通过Git部署配置

安装Git部署插件

安装 Hexo 博客框架中的 Git 部署插件，并将其作为项目的依赖保存。
hexo-deployer-git 是 Hexo 的一个部署插件，它通过 Git 版本控制系统来将生成的静态页面部署到远程服务器或托管平台上。

1	npm install hexo-deployer-git --save

通过执行命令后，安装插件到 Hexo 项目中，并添加到项目的 package.json 文件中的依赖列表中。

在执行 hexo deploy 或 hexo d 命令时，Hexo 将使用 Git 部署插件来将生成的页面提交到预先配置的远程 Git 仓库。

需要注意的是：在安装 hexo-deployer-git 插件之前，需要先在 Hexo 配置文件中进行相应的配置，包括指定部署的 Git 仓库地址、分支信息、用户名密码等。

也就是说，在安装 hexo-deployer-git 插件之前，提前在_config.yml文件中的deploy :type:中填入git：

指定部署方式和相关配置

打开目录下的_config.yml文件。

可以使用VS Code打开，或者记事本、Notepad++都可以。

找到文件最下方的 deploy，添加下列内容：

deploy:
  type: 部署类型
  repo: git@github.com:Github账号用户名/仓库名.git
  branch: 分支名

type: 部署类型：指定部署的类型为 Git，表示使用 Git 作为部署的方式。
repo: git@github.com:Github账号用户名/仓库名.git：指定要部署到的仓库的 Git URL。
branch: 分支名：指定要将静态网页部署到的 Git 分支。在这个例子中，静态网页将被部署到名为 “main” 的分支。

例如：

deploy:
  type: git
  repo: git@github.com:KiraraKira/Kirara.github.io.git
  branch: main

仓库所在的 GitHub 用户是 “KiraraKira”，部署目标是名为 “Kirara.github.io” 的仓库。通过配置，GitHub Pages 会将生成的静态网页部署到仓库中。

远程部署Github Page

hexo deploy 和 hexo d 命令是 Hexo 博客框架中用于部署生成的静态页面的命令，它们是完全等价的，可以互换使用，没有区别。

运行 hexo deploy 或 hexo d 命令时，Hexo 会根据您在配置文件中设置的部署信息，将生成的静态页面部署到相应的远程服务器或平台上，以便将博客内容发布到互联网上。

1
2
3

hexo d

hexo deploy

查看远程部署效果

在Github Pages页面找到 Visit site，点击就可以查看部署到远程的网页

如果远程的链接也能正常打开，就代表配置成功。

修改主题（以Arknights主题为例）

Kiraraの游戏城使用了Arknights主题。具体配置请看github原作者的教程：
https://github.com/Yue-plus/hexo-theme-arknights

下载主题

在项目文件夹下打开git bash，输入：

1	git cloen 想要的主题链接

例如：

1	git clone https://github.com/Yue-plus/hexo-theme-arknights.git themes/arknights

修改配置文件

以下引用自Arknight原作者的教程：

1.参照 Hexo 官网修改 Hexo/ 目录下的 _config.yml。
2.把 theme: 的值改为 arknights
3.开启代码高亮：
1
2
highlight:
hljs: true
4.剪切 Hexo/themes/arknights/_config.yml 到 Hexo 目录下，并重命名为 _config.arknights.yml。
建议参考：
- 使用代替主题配置文件
主题的配置文件可参照中文注释修改。

教程解释：第一步和第二步

下载好主题文件后，打开根目录，找到_config.yml

修改_config.yml中的theme: landscape改为theme: arknights

教程解释：第四步

如下图，剪切主题文件夹中的_config.yml，重命名为：_config.arknights.yml，并粘贴至根目录文件夹下

然后重新执行hexo g来重新渲染静态页面：

修改网站介绍

使用文本编辑器打开 Hexo 项目目录中的 _config.yml 文件，修改站点配置、主题配置、部署配置等

网站介绍相关配置解释

title：设置博客的标题。如：Kiraraの游戏城
subtitle：设置博客的副标题。例如：Kirara
description：设置博客的描述。例如：Kirara的个人主页
author：设置博客的作者。例如：Kirara
language：设置博客的语言。英文为en，中文为zh-CN，需要查看相应的主题使用。
timezone：设置博客的时区。
url：设置博客的 URL 地址。这里的博客URL地址为Github Page页面显示的地址
root：设置博客的根目录。
permalink：设置博客文章的永久链接格式。
date_format：设置博客文章日期的格式。

其他配置都可以自定义，可以按照需要自由修改

本地预览主题

依次执行下面的命令，可以启动本地服务器预览：

1
2
3

hexo clean # 清除public文件夹下的所有文件
hexo g # 将网页生成在public文件夹下
hexo s # 启动本地服务器预览

hexo clean的命令是：清除public文件夹下的所有文件。

清除生成的静态页面：Hexo 在生成静态页面时会将生成的 HTML、CSS、JavaScript 等文件保存在指定的目录中，以便部署到服务器或托管平台上。hexo clean 命令会清除之前生成的静态页面，以便在下一次执行 hexo generate 命令时重新生成新的页面。
清除缓存文件：Hexo 在生成页面时会使用一些缓存文件来提高生成速度和效率。这些缓存文件存储在 .hexo 或 .cache 目录中。执行 hexo clean 命令会清除这些缓存文件，以便下次生成时重新计算和生成缓存。

执行 hexo clean 命令可以清理旧的生成文件和缓存，确保下一次生成的静态页面和缓存文件是基于最新的内容和配置。

在更新博客内容或更改 Hexo 配置时特别有用。

需要注意的是，执行 hexo clean 命令会删除之前生成的静态页面和缓存文件，因此请确保在执行该命令之前备份重要的数据