# 使用 Hexo 和 GitHub Pages 构建静态博客：完整指南


## Hexo 和 GitHub Pages 简介

Hexo 是一个快速、简单而强大的静态博客框架。用户在本地以 Markdown 格式编写博客文章，Hexo 在几秒钟内生成静态 HTML 文件，然后可以发布到博客网站。基于 Node.js 构建，Hexo 可能没有 WordPress 那么多功能，但对于大多数用户的需求来说已经足够了。

GitHub 是一个开源代码管理和共享平台。GitHub Pages 为托管静态网站提供 300MB 的免费空间，最初是为项目文档设计的，但也适用于个人静态博客。

本综合指南详细介绍了如何安装、配置 Hexo 博客框架并将其部署到 GitHub Pages。

## 本地系统环境设置

本指南中的所有本地配置都基于 ArchLinux 操作系统。

由于 Hexo 是基于 Node.js 构建的，而且 GitHub 和 Hexo 都需要 Git 支持，本地环境的主要组件是 Node.js 和 Git 客户端。在安装 Node.js 后，使用 npm 安装 Hexo。

### 安装 Node.js

使用 ArchLinux 内置的包管理器 pacman：

```bash
sudo pacman -S nodejs npm
```

对于其他系统，请参考 [下载和安装 Node.js](https://nodejs.org/en/download/package-manager)

### 安装 Git 客户端

```bash
sudo pacman -S git
```

对于其他系统，请访问 [Git 下载](https://git-scm.com/download) 下载并安装

### 安装 Hexo

使用 npm 安装 hexo-cli 在整个过程中都需要 root 权限。使用 sudo 可能仍然会出现权限错误，因此您必须使用 `su` 切换到 root 用户才能成功安装：

```bash
su
npm install hexo-cli -g
exit
```

## 设置您的本地博客

### 创建博客目录

在本地创建一个文件夹来存储您的博客系统：

```bash
mkdir blog
```

### 初始化博客

```bash
cd blog
hexo init
npm install
```

`hexo init` 命令在当前文件夹中创建博客所需的所有文件。

### 生成静态 HTML 文件

```bash
hexo generate
```

此命令（简写为 `hexo g`）在当前目录中创建一个 public 子文件夹，并在其中生成博客的所有静态 HTML 文件。

### 本地测试

```bash
hexo server
```

简写为 `hexo s`，这会启动一个本地测试 Web 服务器。

打开浏览器并导航到 http://localhost:4000 预览您的博客，其中默认包含一个 Hello World 文章。

## 部署到 GitHub

您的博客系统现在在本地成功运行。下一步是将其发布到远程 Web 服务器。部署本质上涉及将博客目录中 public 子文件夹的所有文件传输到 Web 服务器的目录。您可以以任何喜欢的方式手动上传，或使用 Hexo 的部署插件（deployer）。由于我们要部署到 GitHub Pages，可以使用 Hexo 的 Git 部署插件（hexo-deployer-git）。

### 创建 GitHub 帐户和 Pages 仓库

访问 http://github.com，点击 Sign Up，按照提示注册您的帐户。

注册并登录后，在 GitHub 主页上，点击右上角的 **+** 图标 -> **New Repository**。在项目名称（Project Name）字段中输入 <username>.github.io，其中 <username> 是您的 GitHub 帐户名。其他信息可以留空。点击 **Create Repository** 完成过程。

### 配置本地 Git 客户端用户信息

```bash
git config --global user.name "User Name" # 此用户名是您的真实姓名，不一定与您的 GitHub 用户名相同
git config --global user.email "user@abc.com" # 电子邮件地址必须与您的 GitHub 帐户使用的地址匹配
```

### 安装 Git 部署插件

使用 npm 安装：

```bash
npm install hexo-deployer-git --save
```

### 配置 GitHub 部署

GitHub 部署支持两种连接方式：SSH 和 HTTPS。

#### SSH 配置

使用 SSH 进行部署的优点是初始配置后，每次部署都不需要输入用户名和密码。缺点是初始设置更复杂，并且无法通过代理服务器进行部署。

##### 生成 SSH 密钥

```bash
ssh-keygen -t rsa -C "user@abc.com" # 输入的电子邮件地址必须与您的 GitHub 帐户电子邮件匹配
```

系统会提示您输入保存密钥的文件名 - 保持默认。

按回车后，系统会提示您输入密码。建议留空；否则每次更新或部署博客时都需要输入密码。只需确保 [密钥文件安全](#keysafe)。

##### 将公钥添加到您的 GitHub 帐户

生成本地 SSH 密钥后，您需要将公钥添加到您的 GitHub 帐户设置中。

1. 复制本地主目录中 $HOME/.ssh/id_rsa.pub 文件的所有内容
2. 登录 GitHub，点击右上角的 **Settings** -> **SSH and GPG Keys** -> **New SSH key**
3. 在 Title 字段中输入描述，并将 id_rsa.pub 文件的内容粘贴到 Key 字段中
4. 点击 **Add SSH key**

##### 测试 SSH 连接

使用以下命令测试设置是否成功：

```bash
ssh -T git@github.com
```

首次连接时，您会看到：

```
Are you sure you want to continue connecting (yes/no)?
```

输入 yes，您应该看到：

```
You've successfully authenticated, but GitHub does not provide shell access.
```

这表明成功 SSH 连接到 GitHub。接下来，配置 Hexo 通过 SSH 将您的博客部署到 GitHub Pages。

##### SSH 部署设置

编辑博客文件夹中的 _config.yml 文件。将光标移动到末尾的部署部分：

```yaml
# Deployment
## Docs: https://hexo.io/docs/deployment.html
deploy:
  type: git
  repo: git@github.com:username/username.github.io.git  # 将 username 替换为您的 GitHub 用户名
  branch: master
```

#### HTTPS 配置

使用 HTTPS 进行部署时，每次发布都需要输入您的 GitHub 用户名和密码。优点是初始配置更简单，并且可以 [通过代理服务器](#proxy) 进行部署。例如，我们公司的网络只允许通过代理服务器进行 HTTP/HTTPS 访问互联网。

初始配置只需要编辑博客文件夹中的 _config.yml 文件。将光标移动到末尾的部署部分：

```yaml
# Deployment
## Docs: https://hexo.io/docs/deployment.html
deploy:
  type: git
  repo: https://github.com/username/username.github.io.git  # 将 username 替换为您的 GitHub 用户名
  branch: master
```

### 将您的博客部署到 GitHub Pages

使用 hexo git 部署插件将您的博客部署到 GitHub Pages：

```bash
hexo deploy # 可以简写为 hexo d
# 如果使用 HTTPS，每次部署时都会提示输入用户名和密码
```

然后您可以在 http://username.github.io 浏览您的博客

## 博客文章管理

Hexo 中的所有博客文章都是以 Markdown 格式编写的，源文件保存在 source/_posts 文件夹中。文章管理本质上是管理此文件夹中的文件。

要创建新的博客文章，您可以在此文件夹中创建一个新的 .md 文件，或在您的博客文件夹中执行以下操作：

```bash
hexo new <title> # 文章标题
```

删除或修改博客文章意味着删除或修改相应的 .md 文件。

进行任何更改后，您需要重新生成和部署：

```bash
hexo generate # 可以简写为 hexo g
hexo deploy   # 可以简写为 hexo d
# 上面两行可以合并为 hexo g -d 或 hexo d -g
```

## 附录

<span id="keysafe"></span>

### SSH 密钥文件权限设置

将 SSH 密钥文件及其包含的文件夹设置为只有您自己可读写，其他任何人都没有权限：

```bash
cd ~
chmod 700 .ssh
cd .ssh
chmod 600 *
```

[返回](#ks)

<span id="proxy"></span>

### Git 代理服务器设置

```bash
git config --global http.proxy "proxyserver:port"   # 输入代理服务器地址和端口
git config --global https.proxy "proxyserver:port"  # 输入代理服务器地址和端口
```

[返回](#ps)