使用 Hexo + GitHub Pages + Stellar 主题搭建个人博客

引言

本文将详细介绍如何使用 Hexo 静态网站生成器，结合 GitHub Pages 服务，并应用精美的 Stellar 主题，从零开始搭建一个属于您自己的个人博客。

Hexo 以其超快的生成速度、对 Markdown 的良好支持以及便捷的一键部署功能而闻名，非常适合用来构建个人博客。GitHub Pages 则提供了免费、稳定、可靠的静态网站托管服务。Stellar 主题则能让您的博客拥有现代化且高度可定制的外观。

参考资料：

• 超详细Hexo+Github Pages搭建个人博客教程 - CSDN博客
• Hexo 官方中文文档

一、前置准备

在开始搭建之前，请确保您的系统已安装以下软件：

1. Git: 用于代码的版本控制和部署。
   • 下载地址：https://git-scm.com/downloads
   • 安装后，建议配置 Git 的用户信息：

     1 2	git config --global user.name "您的GitHub用户名" git config --global user.email "您的GitHub邮箱"

   • 参考：使用git拉取github项目-CSDN博客
2. Node.js 和 npm: Hexo 基于 Node.js，npm 是其包管理器。
   • 下载地址：Node.js — Download Node.js®
   • 安装 Node.js 会同时安装 npm。
3. GitHub 账号: 用于创建 GitHub Pages 仓库。
   • 注册地址：https://github.com/

安装完成后，可以在命令行中输入以下命令检查是否安装成功：

1
2
3

node -v
npm -v
git --version

如果能正确显示版本号，则说明安装成功。

二、搭建本地 Hexo 博客

1. 选择一个目录 用于存放您的博客文件，建议路径中不包含中文和特殊字符。例如 C:\MyBlog。
2. 打开命令行工具 (如 Git Bash, Windows Terminal 等)，进入您选择的目录。
3. 安装 Hexo CLI (命令行工具)：

   1	npm install -g hexo-cli

   这将把 Hexo 命令安装到全局环境中，方便在任何地方使用 hexo 命令。
4. 初始化 Hexo 项目: 在您选择的目录下执行以下命令，myblogs 是您的博客项目文件夹名称，可以自定义。

   1 2	hexo init myblogs cd myblogs

   这会在 myblogs 文件夹中创建一个新的 Hexo 项目，并自动安装所需的依赖。
5. 安装项目依赖: 确保您在项目文件夹 (myblogs) 中执行此命令。

   1	npm install

   执行完毕后，您的项目文件夹结构大致如下：

   1 2 3 4 5 6 7 8

   . ├── _config.yml # 站点配置文件 ├── package.json ├── scaffolds # 模板文件夹 ├── source # 博客文章和其他源文件存放处 | ├── _drafts | └── _posts └── themes # 主题文件夹

6. 本地预览: 在项目文件夹中执行以下命令，启动本地服务器预览博客。

   1	hexo server

   默认情况下，博客将在 http://localhost:4000 运行。打开浏览器访问该地址，您应该能看到 Hexo 默认主题的博客页面。

三、创建 GitHub Pages 仓库

1. 登录 GitHub，创建一个新的仓库 (New repository)。
2. 仓库命名规范: 仓库名称必须是 您的GitHub用户名.github.io 的格式。例如，如果您的 GitHub 用户名是 vmoranv，则仓库名称应为 vmoranv.github.io。
3. 选择 Public (公开) 仓库。
4. 勾选 Add a README file (可选，但建议勾选)。
5. 点击 Create repository 创建仓库。
6. 配置 GitHub Pages: 创建仓库后，进入仓库的 Settings -> Pages。
   • 在 Source 部分，选择您希望作为 GitHub Pages 来源的分支 (通常是 main 或 master)。
   • 点击 Save。
   • 稍等片刻，GitHub Pages 会为您生成一个网站，访问地址通常是 https://您的GitHub用户名.github.io。此时访问该地址，您可能只能看到 README 文件的内容或一个简单的页面。

四、配置 Hexo 部署到 GitHub Pages

1. 安装 Git 部署插件: 在您的 Hexo 项目文件夹 (myblogs) 中执行以下命令：

   1	npm install hexo-deployer-git --save

   这个插件允许 Hexo 通过 Git 将生成的静态文件部署到远程仓库。

2. 修改站点配置文件: 打开 Hexo 项目根目录下的 _config.yml 文件。

3. 找到 deploy 部分 (通常在文件末尾)，修改或添加以下配置：

   1 2 3 4 5 6

   # Deployment ## Docs: https://hexo.io/docs/one-command-deployment deploy: type: git repo: git@github.com:vmoranv/vmoranv.github.io.git branch: main

   参考：超详细Hexo+Github Pages搭建个人博客教程 - CSDN博客 中关于 _config.yml 配置和部署报错的解决方案。

4. 部署博客: 在 Hexo 项目文件夹中依次执行以下命令：

   1 2 3

   hexo clean hexo generate hexo deploy

   如果使用 SSH 地址部署，可能会提示输入 SSH Key 密码。如果部署成功，命令行会显示 Deploy done。
   稍等片刻（可能需要几分钟），访问您的 GitHub Pages 地址 https://vmoranv.github.io，您应该能看到部署成功的博客页面。

五、应用 Stellar 主题

1. 下载 Stellar 主题: 在 Hexo 项目文件夹中执行以下命令，将 Stellar 主题克隆到 themes 文件夹：

   1	npm i hexo-theme-stellar

2. 修改站点配置文件: 打开 Hexo 项目根目录下的 _config.yml 文件。
3. 找到 theme 配置项，将其值修改为 stellar：

   1 2	# Themes theme: stellar

4. 配置 Stellar 主题: Stellar 主题有自己的配置文件，位于 themes/stellar/_config.yml。您可以复制此文件到 Hexo 项目根目录下，并重命名为 _config.stellar.yml 进行修改。Hexo 会优先读取项目根目录下的主题配置文件。

   1 2	# 在项目根目录执行 cp themes/stellar/_config.yml _config.stellar.yml

   然后修改项目根目录下的 _config.stellar.yml 文件来配置主题的各种选项，例如导航菜单、侧边栏、社交链接等。
   详细的配置方法请参考 Stellar 主题的开发者文档：https://xaoxuu.com/wiki/stellar/
5. 重新生成和部署: 修改配置后，需要重新生成静态文件并部署才能看到效果：

   1 2 3

   hexo clean # 清理缓存 hexo generate # 生成静态文件 hexo deploy # 部署到 GitHub Pages

六、基本使用：撰写新文章

1. 创建新文章: 在 Hexo 项目文件夹中执行以下命令：

   1	hexo new "文章标题"

   这会在 source/_posts 文件夹下创建一个名为 文章标题.md 的 Markdown 文件。

2. 编辑文章: 打开新创建的 Markdown 文件，您会看到文件顶部有一个 Front-matter 区块，由 --- 包围。Front-matter 是一个 YAML 或 JSON 格式的配置块，用于设置文章的各种属性。Hexo 会根据这些属性来生成页面。

   以下是一些常用的 Front-matter 配置项（使用 YAML 格式）：

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

   --- title: 您的文章标题 # 文章标题，默认为文件名 date: 2025-05-05 22:50:00 # 文章发布日期和时间，默认为文件创建日期 updated: # 文章更新日期和时间，默认为文件修改日期 comments: true # 是否启用评论功能，默认为 true tags: # 文章标签，多个标签用列表形式表示 - 标签1 - 标签2 categories: # 文章分类，可以有多级分类，使用列表和嵌套表示层级 - 分类1 - 子分类 permalink: # 文章的永久链接，会覆盖默认的链接格式，应以 / 或 .html 结尾 excerpt: # 文章摘要，用于首页或列表页展示，纯文本格式 description: # 文章描述，用于 SEO keywords: # 文章关键词，用于 SEO cover: # 文章封面图片链接 layout: post # 文章布局，默认为 post，设置为 false 则不使用主题渲染 published: true # 是否发布文章，对于 _posts 下的文章默认为 true，_drafts 下的默认为 false ---

3. 生成和部署: 文章撰写完成后，执行以下命令生成静态文件并部署到 GitHub Pages：

   1 2 3

   hexo clean hexo generate hexo deploy

七、管理文章资源（图片等）

Hexo 提供了文章资源文件夹（Post Asset Folder）的功能，可以方便地管理每篇文章相关的图片、CSS、JS 等资源。启用此功能后，每次创建新文章时，Hexo 会自动创建一个与文章同名的文件夹，您可以将该文章的所有资源放入其中。

参考资料：Hexo 官方文档 - 资源文件夹

1. 启用文章资源文件夹:

   打开 Hexo 项目根目录下的 _config.yml 文件，找到 post_asset_folder 配置项，将其设置为 true。

   1 2 3

   # _config.yml post_asset_folder: true

2. 创建新文章并管理资源:

   启用此功能后，当您使用 hexo new "文章标题" 命令创建新文章时，Hexo 会在 source/_posts/ 目录下同时创建 文章标题.md 文件和一个名为 文章标题 的文件夹。

   例如，执行 hexo new "我的第一篇文章" 后，您会看到：

   1 2 3

   source/_posts/ ├── 我的第一篇文章.md └── 我的第一篇文章/ # 文章资源文件夹

   您可以将与 我的第一篇文章.md 相关的图片文件（如 image.jpg）放入 source/_posts/我的第一篇文章/ 文件夹中。

3. 在文章中引用资源:

   在文章 (文章标题.md) 中引用资源文件夹内的图片时，推荐使用 Hexo 提供的标签插件 asset_img，以确保在首页、归档页和文章详情页都能正确显示图片。

   1	{% asset_img image.jpg [图片alt文本] %}

   例如，引用 source/_posts/我的第一篇文章/image.jpg：

   1	{% asset_img image.jpg 我的第一篇文章配图 %}

   如果您希望使用标准的 Markdown 语法 ![](image.jpg) 来引用图片，需要额外配置 hexo-renderer-marked 插件。在 _config.yml 中添加或修改以下配置：

   1 2 3 4 5

   # _config.yml marked: prependRoot: true postAsset: true

   启用此配置后，您就可以在文章中使用相对路径的 Markdown 语法引用资源文件夹内的图片了：

   1	

八、使用可视化工具管理博客

Hexo 本身是一个命令行工具，但您可以使用第三方可视化工具来提供图形化界面，方便管理和撰写博客。常见的可视化工具包括 Hexo Admin 和 Hexon。

参考资料：Windows部署Hexon可视化博客环境

使用 Hexo Admin

Hexo Admin 是一个 Hexo 的管理插件，可以在浏览器中提供一个简单的管理界面。

1. 安装 Hexo Admin: 在您的 Hexo 项目文件夹中执行以下命令：

   1	npm install --save hexo-admin-yf

2. 启动 Hexo 服务器: 在项目目录下，启动 Hexo 服务器：

   1	hexo server

3. 访问 Hexo Admin: 打开浏览器，访问 http://localhost:4000/admin。您可以在这里进行文章的创建、编辑、删除以及博客设置的管理。

关于 Hexon

Hexon 是另一个带有 Git 功能的 Hexo 图形化界面工具。根据参考资料，它提供了运行命令和管理内容的功能。如果您对 Hexon 感兴趣，可以访问其 GitHub 仓库了解更多信息：https://github.com/gethexon/hexon。

许可协议

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

分享文章