Hexo博客搭建教程

---

Part 1: 前言：为何选择 Hexo？

市面上有多种博客搭建方式：动态博客（如 WordPress），或静态博客（Hexo, Hugo, Jekyll）。

Hexo 的优势在于：

• 极速生成： 亿级文件也只需几秒，高效转换为静态页面。
• 简洁易用： 使用 Markdown 写作，简单易学，专注于内容。
• 免费托管： 静态网站可部署在 GitHub Pages, Gitee Pages, Netlify 等免费平台，无需服务器和数据库费用。
• 丰富主题与插件： 拥有庞大的社区，提供大量精美主题和强大插件，可高度定制。
• Git 版本控制： 所有内容都在本地，便于使用 Git 进行版本管理。

对于个人博客、技术分享、作品展示等场景，Hexo 是一个绝佳的选择。

Part 2: 第一步：环境准备（Node.js & Git）

在开始 Hexo 之前，你需要准备两个重要的工具：Node.js 和 Git。Hexo 是基于 Node.js 运行的，而 Git 则用于版本控制和将你的博客部署到 GitHub Pages。

2.1 安装 Node.js

Node.js 集成了 npm (Node Package Manager)，用于安装和管理 Hexo 及其他依赖包。

1. 下载： 访问 Node.js 官网：nodejs.org。

2. 选择版本： 推荐下载 LTS (Long Term Support) 版本，这个版本更稳定。

3. 安装： 按照安装程序的提示一步步完成即可。在安装过程中，确保勾选了 “Add to PATH” 选项，这样你就可以在任何地方使用 node 和 npm 命令了。

4. 验证安装： 打开命令行工具（Windows: PowerShell 或 CMD；macOS/Linux: 终端），输入以下命令并回车：

   node -v
   npm -v

   如果显示版本号（如 v16.14.0 和 8.3.1），说明 Node.js 和 npm 已成功安装。

2.2 安装 Git

Git 用于版本控制和将文件推送到 GitHub (或其他代码托管平台)。

1. 下载： 访问 Git 官网：git-scm.com。

2. 安装： 按照安装程序的提示一步步完成。默认选项通常是最好的选择，尤其是在 “Adjusting your PATH environment” 步骤中选择 “Git from the command line and also from 3rd-party software”。

3. 验证安装： 打开命令行工具，输入：

   git --version

   如果显示版本号，说明 Git 已成功安装。

4. 配置 Git (全局设置): 在命令行中输入以下命令，替换成你的 GitHub 用户名和邮箱（如果你没有 GitHub 账号，可以先用常用邮箱）：

   git config --global user.name "你的GitHub用户名"
   git config --global user.email "你的邮箱地址"

   这是提交代码时用于识别作者身份的。

---

Part 3: 第二步：安装 Hexo 并初始化博客

环境准备就绪，现在开始安装 Hexo 并创建你的第一个博客！

3.1 全局安装 Hexo CLI

打开命令行工具，输入以下命令进行安装：

npm install -g hexo-cli

-g 参数表示全局安装，这样你就可以在任何目录下使用 hexo 命令了。

3.2 创建你的博客项目

选择一个你喜欢的目录来存放你的博客文件（例如 D:/MyBlog 或 ~/Documents/MyBlog）。进入该目录，并执行 Hexo 初始化命令：

# 进入你希望存放博客的目录
cd D:/MyBlog  # 示例：Windows 系统
# cd ~/Documents/MyBlog # 示例：macOS/Linux 系统

# 初始化一个新的 Hexo 站点，这里的 `my-hexo-blog` 是你的博客文件夹名，可以自定义
hexo init my-hexo-blog

# 进入新创建的博客目录
cd my-hexo-blog

# 安装项目依赖 (这里会下载运行 Hexo 所需的核心库和工具)
npm install

npm install 可能需要一些时间，因为它会从 npm 仓库下载大量依赖包。耐心等待。

至此，你的第一个 Hexo 博客项目已经创建并初始化成功！目录结构类似：

my-hexo-blog/
├── _config.yml      # 站点配置文件 (非常重要！)
├── package.json
├── scaffolds/       # 文章模板文件夹
├── source/          # 源代码文件夹（放置文章、页面等内容）
│   └── _posts/      # 博客文章存放处
└── themes/          # 主题文件夹
    └── landscape/   # 默认主题 landscape

3.3 本地预览你的博客

现在，我们可以在本地启动 Hexo 服务，预览你的博客效果：

hexo generate  # 缩写：hexo g, 用于生成静态文件 (这一步不是必需的，hexo server 会自动做)
hexo server    # 缩写：hexo s, 启动本地服务器

在命令行中，你会看到类似 INFO Hexo is running at http://localhost:4000 . Press Ctrl+C to stop. 的提示。

打开你的浏览器，访问 http://localhost:4000。恭喜！你已经看到了你的 Hexo 博客的庐山真面目。默认情况下，它会展示一个“Hello World”的示例文章。

要停止本地服务器，在命令行中按下 Ctrl + C。

---

Part 4: 第三步：基础配置与内容创作

现在我们来个性化你的博客，并尝试写一篇新文章。

4.1 博客根配置文件 _config.yml

这个文件是整个 Hexo 博客的核心配置文件，所有全局设置都在这里进行。

打开你的博客根目录下的 _config.yml 文件。建议使用支持 YAML 格式的文本编辑器（如 VS Code, Sublime Text），注意 YAML 格式对缩进非常敏感，务必使用空格进行缩进，不要使用 Tab 键。

一些常用配置项（按实际需求修改）：

# Site 配置项：
title: 我的技术博客  # 你的博客标题
subtitle: 分享编程与生活  # 副标题
description: 一个记录我的学习与思考的个人博客。  # 博客描述，用于SEO
keywords: Hexo, 博客, 技术, 教程, 个人  # 网站关键词
author: 你的名字  # 你的名字
language: zh-CN  # 语言，可根据需要改成 en, ja, zh-TW 等
timezone: 'Asia/Shanghai'  # 时区，对应实际地点

# URL 配置项： (在部署时会详细解释)
url: http://yoursite.com  # 博客网址，部署后填入你的域名，很重要！
root: /
permalink: :year/:month/:day/:title/
permalink_defaults:
pretty_urls:
  trailing_index: true # Set to false to remove “index.html” at the end of a URL
  trailing_html: true # Set to false to remove “.html” at the end of a URL

每次修改 _config.yml 文件后，可能需要运行 hexo clean 清理缓存并重新生成静态文件，或重新启动 hexo server 来查看效果。

4.2 创建第一篇文章

Hexo 创建文章非常简单。在命令行中，进入你的博客根目录（my-hexo-blog），执行：

hexo new post "我的第一篇博客"

这会在 source/_posts/ 目录下创建一个名为 我的第一篇博客.md 的 Markdown 文件。

打开这个文件，你会看到文件顶部有一段由三个短横线包围的内容，这被称为 Front-matter，它是文章的元数据：

---
title: 我的第一篇博客   # 文章标题
date: 2024-07-31 10:00:00 # 文章发布日期
tags: # 文章标签
  - Hexo
  - 入门
categories: # 文章分类
  - 博客教程
---

# 这是我的第一篇文章！

Hexo 真是一个很棒的工具，能帮助我轻松地创建和发布博客。

你可以在这里开始你的写作之旅。
支持 Markdown 语法，比如：

## 二级标题

### 三级标题

**加粗文本**

* 斜体文本

* 列表项1
* 列表项2

`单行代码`

```javascript
// 代码块
console.log("Hello, Hexo!");

在 Front-matter 下方就可以使用标准的 Markdown 语法撰写你的文章内容了。

### 4.3 发布你的文章（生成与本地预览）

修改完文章和配置后，保存文件，然后再次运行：

```bash
hexo clean  # 清理缓存，推荐每次更改主题或重要配置后运行
hexo generate # 缩写 hexo g, 生成静态文件
hexo server   # 缩写 hexo s, 启动本地服务器预览

再次访问 http://localhost:4000，你应该就能看到你新发布的文章了！

---

Part 5: 第四步：美化你的博客（主题安装与配置）

Hexo 最吸引人的地方之一就是丰富的主题！默认的 landscape 主题可能无法满足你的审美需求。

5.1 挑选并安装主题

1. 浏览主题： 访问 Hexo 官方主题页面：hexo.io/themes/。在这里，你可以看到大量的开源主题。点击你感兴趣的主题，通常会有一个演示站点。

2. 下载主题： 找到喜欢的主题后，复制其 GitHub 仓库地址。以流行的 Butterfly 主题为例：

   # 进入你的博客根目录 my-hexo-blog
   cd my-hexo-blog
   
   # 下载主题到 themes 文件夹下
   git clone https://github.com/Jerryc05/Hexo-Theme-Butterfly.git themes/butterfly
   # 或直接访问主题的 GitHub 页面，找到 README.md 中的安装教程，按教程操作

   下载过程完成后，你会看到 themes 目录下多了一个 butterfly 文件夹（或其他你下载的主题名称）。

3. 启用主题： 打开你的博客根目录下的 _config.yml 文件。找到 theme: 这一项，将默认的 landscape 改为你下载的主题名称。

   # _config.yml
   #...其他配置...
   theme: butterfly # 将 landscape 改为你下载的主题文件夹名称
   #...

5.2 主题配置 _config.yml

几乎所有主题都有自己的配置选项，这些配置项通常写在主题文件夹下的一个名为 _config.yml (或 _config.butterfly.yml，具体看主题说明) 的文件中。

重要提示：不要直接修改主题目录下的 _config.yml 文件！ 因为当你更新主题时，这些修改可能会被覆盖掉。

Hexo 提供了更好的主题配置方式：
将主题配置文件中你想要修改的部分，复制到你博客根目录下的 _config.yml 文件中 (不是主题目录的，是整个博客目录的)。
这些复制过来的配置项，一定要写在主 _config.yml 文件的最后。
Hexo 会在加载配置时，优先加载主 _config.yml，然后用主题配置进行覆盖，但如果你在主配置文件中定义了与主题配置相同的参数，主配置会覆盖主题的配置。

通常的做法是，创建一个站点级别的覆盖文件，具体方法可能因主题而异，请务必查看你所选主题的官方文档，它会详细指导你如何正确配置主题。

配置完主题后，同样需要 hexo clean、hexo generate、hexo server 来刷新本地预览效果。

---

Part 6: 第五步：部署你的博客（上线）

你已经有了自己的本地博客，现在是时候把它部署到线上，让全世界都能访问了！

6.1 什么是部署？选择 GitHub Pages

部署就是将本地生成的静态博客文件上传到 Web 服务器，使其可以通过互联网访问。对于静态博客，最常见也最方便的免费托管服务是 GitHub Pages。

GitHub Pages 工作原理：
你将博客生成的静态 HTML、CSS、JS 文件推送到 GitHub 仓库的特定分支 (如 main 或 gh-pages)，GitHub 就会将其作为网站提供访问服务。

6.2 GitHub Pages 配置

1. 创建 GitHub 仓库：

   • 登录 GitHub。
   • 点击右上角的 + -> New repository。
   • 仓库名称： 非常重要！如果你想用 GitHub 的免费二级域名 yourusername.github.io，那么你的仓库名必须是 yourusername.github.io (其中 yourusername 是你的 GitHub 用户名)。
   • 设为 Public，不勾选 Add a README file，然后点击 Create repository。

2. 为仓库添加 SSH Key (推荐)：
   为了每次部署无需输入用户名密码，可以使用 SSH key 进行免密登录。

   • 在命令行中执行 ssh-keygen -t rsa -b 4096 -C "你的邮箱"，然后一路回车。
   • 执行 cat ~/.ssh/id_rsa.pub (macOS/Linux) 或 type C:\Users\你的用户名\.ssh\id_rsa.pub (Windows)，复制显示的内容。
   • 回到 GitHub，点击头像 -> Settings -> SSH and GPG keys -> New SSH key。
   • Title 随便填，Key 粘贴你刚刚复制的内容。
   • 点击 Add SSH key。

6.3 安装部署插件

Hexo 部署到 Git 需要一个专门的插件：hexo-deployer-git。在你的博客根目录下运行：

npm install hexo-deployer-git --save

--save 参数表示将此插件保存到 package.json 的依赖列表中。

6.4 修改 _config.yml 配置部署

再次打开你的博客根目录下的 _config.yml 文件，找到 deploy: 部分。修改为如下配置：

# Deployment 配置项：
deploy:
  type: git
  # 仓库地址：如果你是 yourusername.github.io 这样的个人博客，请使用 SSH 链接
  # repo: git@github.com:yourusername/yourusername.github.io.git
  # 如果不是你的用户名开头的仓库，可以 https 或者 ssh，通常 ssh 免密更好用
  repo: git@github.com:yourusername/your_blog_repo.git # 将 yourusername/your_blog_repo 替换为你实际的 GitHub 仓库地址和名称

  # 分支名称：通常部署到 gh-pages 或 main 分支。对于 yourusername.github.io 这样的，一般部署到 main 分支。
  branch: main # 确保你的 GitHub 仓库对应的 GitHub Pages 构建分支是 main (可在仓库设置中查看)
  message: "Hexo updated: {{ now('YYYY-MM-DD HH:mm:ss') }}" # 每次部署的 Git 提交信息

重要：repo 中的地址一定要填写正确，并且替换为你的 GitHub 用户名和对应的仓库名！branch 也请根据你的 GitHub Pages 仓库设置确认。

6.5 执行部署命令

一切就绪！在你的博客根目录下，执行以下“三连”命令：

hexo clean      # 清理之前生成的静态文件和缓存
hexo generate   # 重新生成最新的静态文件
hexo deploy     # 缩写 hexo d, 将生成的静态文件推送到 GitHub 仓库

如果出现提示询问你是否提交（如 [Y/N]），输入 Y 并回车。
首次部署可能需要一些时间，因为 GitHub Pages 需要几分钟来处理和发布你的网站。

6.6 访问你的博客！

成功部署后，你应该可以在以下地址访问你的博客：
https://yourusername.github.io (如果你创建了 yourusername.github.io 这样的仓库)
或者 https://yourusername.github.io/your_blog_repo/ (如果你是在一个非 yourusername.github.io 的仓库部署的，那一般默认访问地址会带上你的项目名)。

重要：如果无法访问或显示 404，请检查以下几点：

1. GitHub Pages 设置： 进入你的 GitHub 仓库 -> Settings -> Pages。确保 GitHub Pages 已经启用，并且 Source 部分指向了正确的发布分支 (main 或 gh-pages)。通常默认是 main 分支。
2. _config.yml 中 url 和 root 配置： 如果你的仓库是 yourusername.github.io，那么 url: https://yourusername.github.io，root: /。
   如果你的仓库是 yourusername/your_blog_repo，那么 url: https://yourusername.github.io/your_blog_repo，root: /your_blog_repo/。
   url 和 root 配置的正确性直接影响 CSS/JS 资源的加载。

---

Part 7: 拓展与进阶

7.1 自定义域名

如果你觉得 yourusername.github.io 不够酷，你可以为你的博客绑定一个自定义域名 (如 www.yourblog.com)。

1. 购买域名： 到阿里云、腾讯云、Godaddy 等域名注册商购买你心仪的域名。
2. DNS 解析：

   • 在域名提供商的 DNS 管理后台添加 DNS 解析记录。

   • 方法一：A 记录指向 GitHub Pages IP (推荐稳定):

     主机记录: @ (或 www)  | 记录类型: A  | 记录值: 185.199.108.153 (这是 GitHub Pages 的一个常用 IP，注意IP可能变化，可查找最新IP)
     主机记录: @ (或 www)  | 记录类型: A  | 记录值: 185.199.109.153
     主机记录: @ (或 www)  | 记录类型: A  | 记录值: 185.199.110.153
     主机记录: @ (或 www)  | 记录类型: A  | 记录值: 185.199.111.153

   • 方法二：CNAME 记录指向你的 GitHub Pages 域名 (推荐简便):

     主机记录: www       | 记录类型: CNAME | 记录值: yourusername.github.io. (注意末尾的 `.` 有时需要，取决于 DNS 提供商)

     同时为你的顶级域名 @ (或解析服务商可能写作 *) 添加一个重定向，重定向到 www 的域名。

3. GitHub 仓库设置：
   • 在你的 GitHub Pages 仓库中，进入 Settings -> Pages。
   • 在 Custom domain 下输入你的自定义域名 (如 www.yourblog.com)，点击 Save。
   • GitHub 会自动在你的仓库根目录下创建一个名为 CNAME 的文件，内容就是你的自定义域名。hexo deploy 会自动保留这个文件。
   • 勾选 Enforce HTTPS，让你的博客通过 HTTPS 访问。

7.2 常用命令总结

• hexo init <folder>: 初始化新博客到指定文件夹
• hexo new [layout] <title>: 创建新文章/页面 (post, page, draft)
• hexo clean: 清理缓存文件 (db.json) 和生成的静态文件 (public 目录)
• hexo generate / hexo g: 生成静态文件
• hexo server / hexo s: 启动本地服务器预览 (默认 http://localhost:4000)
• hexo deploy / hexo d: 部署网站
• npm install <plugin-name> --save: 安装 Hexo 插件

7.3 插件扩展

Hexo 的强大也体现在其丰富的插件生态。你可以在 Hexo 官方插件页面 hexo.io/plugins/ 查找感兴趣的插件，例如：

• 搜索功能： hexo-generator-searchdb (或主题自带的搜索功能)
• RSS 订阅： hexo-generator-feed
• sitemap 生成： hexo-generator-sitemap
• 压缩优化： hexo-renderer-less, hexo-uglify

每个插件的安装和配置方式略有不同，请查阅其文档。

---

Part 8: 总结

恭喜！你已经成功搭建并部署了你的第一个 Hexo 博客。这是一个激动人心的开始！

通过本教程，你学会了：

• 安装 Node.js 和 Git。
• 使用 Hexo 初始化项目、管理文章。
• 配置博客、安装并美化主题。
• 最终将博客免费部署到 GitHub Pages。

静态博客的优势在于其极致的速度和稳定性，且后期维护成本极低。你现在可以尽情享受写作的乐趣，并不断探索 Hexo 丰富的定制选项和插件，将你的博客打造成你心中的理想模样。

开始你的创作之旅吧！有什么问题，随时都可以查阅 Hexo 官方文档，或在社区寻求帮助。祝你博客之旅愉快！