Hexo+GitHub Pages 搭建个人博客

[TOC]

安装 Node.js 、 npm 和 Hexo CLI

安装 node.js 和 npm。
1
sudo pacman -S nodejs npm

安装 hexo 。

1
2
3

sudo npm install -g hexo-cli
# 也可以使用 yay 安装
yay -S hexo-cli

本地部署

建议

可选，新建一个文件夹存放所有博客相关内容，方便管理。

1	mkdir BlogAll

新建并初始化博客

文件夹名以 YuanmxcBlog 为例。

cd BlogAll
mkdir YuanmxcBlog
cd YuanmxcBlog
hexo init # 初始化，这会在当前目录下生成一些默认文件
npm install # 安装 package.json 内的项目所需的依赖包在 node_modules 内

初始化博客文件夹后，会在当前目录下生成一些默认文件。

1
2
3

❯ ls
_config.landscape.yml  node_modules  package-lock.json  source
_config.yml            package.json  scaffolds          themes

博客相关文件简单介绍

_config.yml

Hexo 的默认主配置文件。包括站点的全局配置，例如网站标题、描述、URL、语言、分页设置、部署配置等。用于控制网站的全局行为和外观。
_config.landscape.yml

用于特定场景或主题的附加配置文件。Hexo 默认主题 landscape 的配置文件（如果你未使用此主题，可忽略或删除）。后面更改主题时，不同主题或环境需要不同配置，会创建类似的文件。可以覆盖或扩展主配置文件中的某些配置。
node_modules

文件夹内包含通过 npm 安装的所有 Node.js 模块和依赖包。Hexo 本身及其插件的所有依赖都在这里。
package-lock.json

npm 自动生成的文件，记录了项目中所有已安装包的具体版本及其依赖关系。保证每次安装依赖时使用的版本一致，确保环境的可重复性。
package.json

定义了项目的基本信息（如名称、版本），列出了项目的依赖包以及可执行的脚本（如 Hexo 核心包、插件等）。管理项目依赖和 npm 脚本，帮助开发者维护和分享项目。
source

用于存放网站内容的文件夹。所有文章、页面、资源（如图片、视频）都放在这里。存储和组织博客内容。
scaffolds

包含模板文件的文件夹，定义新文章或页面的初始结构。当通过 hexo new 创建新文章或页面时，会基于这些模板生成文件。
themes

用来存放网站的主题。每个主题都有其独立的文件夹，其中包含模板、样式表、脚本和其他资源。控制网站的外观和布局。

生成和预览博客

1	hexo new “HelloWorld”

生成 HelloWorld.md 文件（你的文章），存放在 /your_blogyour_blog/sources/_post/ 目录下。该目录下会存放执行该命令后生成的静态站点文件（用于部署）。

1	hexo generate

使用缩写 hexo g 亦可。该命令会将 /your_blog/sources/_post/ 目录下的 Markdown 文件解析成可以使用浏览器查看的 HTML 文件，存在 blog/public 目录下。同时生成 db.json 文件。

**db.json **

Hexo 的 缓存数据库，用于存储文章、页面等数据的元信息，加速生成过程。如果文章内容或配置有变化，Hexo 会自动更新此文件。
public

由 hexo generate（或 hexo g）命令生成，存放命令生成的静态网站文件，包含所有渲染后的 HTML、CSS、JS 和资源文件（图片等）。

1	hexo server

使用缩写 hexo s 亦可。该命令会在本地运行服务，可以在提示的网址进行预览博客。(目前使用的是默认主题，后面可以根据自己喜好更换其他主题)。

Hexo 配合 GitHub Page 部署

新建一个 GitHub 仓库

新建仓库

在你的 GtiHub 上新建一个仓库，仓库权限设为 public，仓库名格式为 <你的GitHub用户名>.github.io 。这里以 Yuanmxc.Github.io 为例。或者使用自定义的仓库名，这里以 YuanmxcBlog为例。两者有些许差异。
1（<username>.github.io）
- 部署位置：自动映射到根域名
  - 访问地址：https://<username>.github.io
  - 直接解析仓库根目录内容（无需子路径）
- 分支要求：必须使用master/main分支
- 用途特性：
  - 每个账户只能有1个此类仓库
  - 适合作为个人主站/博客入口
  - 支持绑定顶级自定义域名（如yourdomain.com）
1. 普通项目仓库（任意名称）
- 部署位置：自动添加仓库名作为子路径
  - 访问地址：https://<username>.github.io/<repo-name>
- 分支灵活：
  - 可选择gh-pages分支
  - 或master/main分支的/docs目录
- 用途特性：
  - 适合项目文档或子站点
  - 每个项目独立部署
  - 可绑定子域名（如blog.yourdomain.com）
设置 Pages 页面

打开仓库的 Setting 的 Pages 设置，根据你自己的情况进行设置。如果有自己购买的域名，可以设置上（请自行查看其他教程）。

我的示例：

设置 Hexo 远程部署方式为 Github

在 YuanmxcBlog 目录下安装使用 Git 进行部署所需的依赖项。

1	npm install hexo-deployer-git --save

在 YuanmxcBlog/_config.yml 中修改 deploy 属性（注意:之后有空格）。

deploy:
  type: git
  repository: [你的仓库地址,如果有ssh推荐使用ssh]
  # 例如：https://github.com/Yuanmxc/YuanmxcBlog
  # 例如：https://github.com/Yuanmxc/Yuanmxc.github.io
  branch: main

第一次远程部署

1	hexo deploy

使用 hexo d 亦可，这个命令会将本地的 public 目录的内容复制到 .deploy_git （新生成的）目录内下。

.deploy_git

这个目录就是 Git 管理的目录，与你上面配置文件中填入的 GitHub 仓库进行绑定，然后通过 Git 操作（git add, git commit, git push）将内容推送到你配置的 GitHub Pages 仓库。同时更新你的 Github page 个人博客展示界面（可能有延迟）。

此时你的目录下应该有以下文件：

❯ ls -a
.            _config.yml        node_modules  source
..           db.json            package.json  themes
.deploy_git  package-lock.json  .github       public
_config.landscape.yml           .gitignore    scaffolds

比之前多了 5 个文件。除了db.json、 public 目录和 deploy_git 目录外，剩下两个生成的文件简单解释如下：

.github 目录

GitHub 相关目录，存放 GitHub Actions 的配置文件（如 .github/workflows/xxx.yml），用于自动化部署或其他 CI/CD 流程。
.gitignore 文件

定义 Git 忽略的文件/目录，避免将临时文件、依赖项等提交到仓库。

常见忽略项：
- node_modules/：npm 依赖目录。
- public/：生成的静态文件。
- .deploy_git/：部署临时目录。
- db.json：Hexo 的缓存数据。

后续更新

经过上面的步骤，你现在已经在本地和 GitHub Pages 部署了你的博客，并可以通过特定的域名去访问它。

以后更新博客

写文章：

使用 Typora 等 Markdown 编辑器，在 YuanmxcBlog/sources/_post/目录下创建 Markdown 文件，并编辑。

生成静态文件、本地预览、推送远程更新。

1
2
3

hexo g # 将Markdown文件解析成HTML文件
hexo server # 本地预览（可无）
hexo d # 推送远程更新

注意

短时间内对本地配置文件进行修改后，推荐使用 Hexo cl 命令来清除缓存，之后在执行 Hexo s 来查看修改后的效果。
你的 Github 本地仓库应该位于 YuanmxcBlog 目录，并且名为 .deploy_git，不要更改，博客网站就是目录下的文件生成的。执行 hexo d 命令时会自动帮你更改仓库中的文件，不需要手动处理。同时，执行 hexo 命令需要在 YuanmxcBlog 目录下进行操作。