Hexo + GitHub Pages 从零搭建博客详细步骤

注意：快速判断你的 Mac 芯片：点击左上角苹果图标 → 「关于本机」，查看「芯片」一栏，显示「Apple Mx」就是 Apple Silicon，显示「Intel Core」就是 Intel 芯片。

注意：快速判断你的 Windows 架构：打开「设置 → 系统 → 关于」，查看「系统类型」，显示「64 位操作系统，基于 x64 的处理器」就是普通 64 位；显示「基于 ARM 的处理器」就是 ARM 64 位。

1.1.3 Node.js 的安装

双击下载的文件。

点击 Next.

这是 Node.js 安装过程中的最终用户许可协议（End-User License Agreement，EULA）页面。

• 这个页面是软件安装的标准流程，里面的文字是你和 Node.js 官方之间的使用协议，大意是：官方免费允许你使用、复制、修改和分发 Node.js 软件，但需要遵守一些开源协议的条件（比如不得用于非法活动、保留版权声明等）。
• 你已经勾选了「I accept the terms in the License Agreement」（我接受许可协议中的条款），这是继续安装的必要条件。

下一步操作：直接点击右下角的 Next 按钮，就能进入下一步的安装路径选择界面了。

根据自己需求选择安装位置，一般不建议安装在 C 盘。

这是 Node.js 安装过程中的自定义安装配置界面，各选项说明如下：

• Node.js runtime：Node.js 核心运行环境，必须保留，它是运行 Node.js 程序的基础。
• corepack manager：官方包管理器工具，用于管理 npm、yarn 等工具，默认勾选即可。
• npm package manager：Node.js 自带的包管理工具，安装 Hexo 等依赖必须用到它，必须保留。
• Online documentation shortcuts：在线文档快捷方式，会在桌面生成文档链接，可选（不影响核心功能）。
• Add to PATH：自动将 Node.js 添加到系统环境变量中，这是最关键的选项，必须保留。如果取消，后续在终端里无法直接使用 node、npm 等命令。

当前界面的默认勾选配置已经是最优选择，不需要修改任何选项，直接点击右下角的 Next 按钮继续安装流程即可。

这是 Node.js 安装中的原生模块编译工具配置界面：

这个选项是用来安装编译 C/C++ 原生模块所需的工具（如 Python、Visual Studio Build Tools），仅当你需要安装依赖原生代码的 npm 包时才需要。

Hexo 及其依赖都是纯 JavaScript 编写的，完全不需要编译原生模块，因此：

• 不需要勾选'Automatically install the necessary tools' 这个选项，避免安装不必要的工具，节省时间和磁盘空间。
• 直接点击右下角的 Next 按钮，继续完成安装即可。

后续问题处理：如果之后你安装其他 npm 包时遇到'需要编译原生模块'的错误，再根据提示手动安装这些工具也完全来得及。

直接点击 install 即可。

等待安装即可。

安装完成，点击 finish 或者点击叉掉。

1.1.4 验证安装

打开电脑终端（Windows 用 cmd/PowerShell，Mac/Linux 用 Terminal），输入：

node -v
npm -v

运行能看到版本号就说明安装成功。

1.2 安装 Git（推送代码到 GitHub 用）

把本地博客代码推送到 GitHub 仓库，实现部署。

1.2.1 下载安装包

打开 Git 官网：https://git-scm.com/

点击页面中间的 Download for Windows（Windows 用户），会自动下载最新稳定版安装包。

1.2.2 安装 Git

这是 Git 安装向导的第一步，你只需要点击 Next 按钮继续就可以了。

根据自己的选择，选择安装地址。

介绍各个选项：

1. Additional icons → On the Desktop

   • 作用：在你的电脑桌面上创建 Git Bash 和 Git GUI 的快捷方式图标。
   • 建议：新手可以勾选，方便快速启动 Git；如果习惯用右键菜单或终端启动，也可以不勾选。

2. Windows Explorer integration

   • Open Git Bash here：在文件夹右键菜单中添加'Git Bash Here'选项，让你可以直接在当前文件夹打开 Git 终端。必须勾选！这是日常使用 Git 最频繁、最方便的功能。
   • Open Git GUI here：在文件夹右键菜单中添加'Git GUI Here'选项，打开图形化的 Git 管理工具。可选。

3. Git LFS (Large File Support)

   • 作用：支持 Git 管理大文件（如数据集、视频、大型模型文件等），避免仓库体积过大。
   • 建议：建议勾选。虽然你现在用 Git 管理代码，但后续学习机器学习时可能需要上传数据集，提前开启更省心。

4. Associate .git configuration files with the default text editor

   • 作用：让 .gitconfig、.gitignore 等 Git 配置文件，默认用你指定的编辑器（如 VS Code）打开。
   • 建议：建议勾选。后续修改 Git 配置文件时会更方便。

5. Associate .sh files to be run with Bash

   • 作用：让 .sh 格式的 Shell 脚本文件，默认用 Git Bash 来运行。
   • 建议：建议勾选。后续如果用到 Hexo 或其他工具的 Shell 脚本，这个设置会更便捷。

6. Check daily for Git for Windows updates

   • 作用：每天自动检查 Git 是否有新版本，并提示你更新。
   • 建议：可选。

7. Add a Git Bash Profile to Windows Terminal

   • 作用：在 Windows 自带的 Terminal 中添加 Git Bash 的配置文件。
   • 建议：可选。

8. Scalar (Git add-on to manage large-scale repositories)

   • 作用：一个 Git 扩展工具，用于管理超大型代码仓库。
   • 建议：可选。对于个人博客、学习项目这类小型仓库，完全用不到。

这个界面是在设置 Git 程序在 Windows「开始菜单」中的快捷方式存放位置。保持默认最清晰。

这个界面是让你选择 Git 在需要编辑文本时（比如写提交信息、修改配置文件）默认使用的编辑器。

• 默认选项（Vim）：Vim 是一个功能强大的终端编辑器，但它的操作逻辑和快捷键对新手非常不友好。
• 下拉菜单：推荐选择 Visual Studio Code，它是图形化界面，编辑起来更直观。

这个界面是设置你用 git init 新建仓库时，默认的主分支名称。

• Let Git decide（默认选项）：Git 会用它默认的分支名（目前是 master）作为新仓库的初始分支。
• Override the default branch name for new repositories：你可以自定义新仓库的默认分支名，比如 main。

这个界面是设置 Git 在系统中的可访问方式，也就是调整环境变量 PATH。

1. Use Git from Git Bash only：仅允许在 Git Bash 终端里使用 Git 命令。缺点：后续用 Hexo 时，可能需要在不同终端里执行 Git 命令，这个选项会导致命令无法识别。
2. Git from the command line and also from 3rd-party software（推荐选项）：这是安装程序推荐的选项，它会把最精简的 Git 工具添加到系统 PATH 中。你可以在 Git Bash、Command Prompt、PowerShell 等各种终端里使用 Git 命令，同时第三方软件（如 Hexo）也能正常找到 Git。
3. Use Git and optional Unix tools from the Command Prompt：会把 Git 和一些 Unix 工具都添加到 PATH 中，可能引发冲突。新手不建议选择。

这个界面是让你选择 Git 连接远程仓库（比如 GitHub）时使用的 SSH 客户端程序。

1. Use bundled OpenSSH（默认选项）：使用 Git 自带的 OpenSSH 客户端，无需额外安装或配置，兼容性最好。对新手最友好。
2. Use external OpenSSH：使用你系统中已有的外部 OpenSSH 客户端。新手选择这个容易出现路径识别问题，不推荐。

这个界面是选择 Git 建立 HTTPS 连接时使用的 SSL/TLS 加密库。

1. Use the OpenSSL library：使用独立的 OpenSSL 库。适合跨平台场景。
2. Use the native Windows Secure Channel library（默认选中）：使用 Windows 系统原生的安全通道库。和个人用户和新手来说更省心。

这个界面是配置 Git 如何处理文本文件中的换行符。

1. Checkout Windows-style, commit Unix-style line endings（默认选中）：拉取文件时将 Unix 换行符转换为 Windows 换行符，提交时转回为 Unix 换行符。这是 Windows 系统的官方推荐设置。
2. Checkout as-is, commit Unix-style line endings：拉取文件时不做转换，提交时才转换。适合 Unix 系统用户。
3. Checkout as-is, commit as-is：拉取和提交时都不转换换行符。不推荐跨平台项目。

这个界面是为 Git Bash 选择终端模拟器。

1. Use MinTTY (the default terminal of MSYS2)（默认选中）：窗口可以自由调整大小，支持 Unicode 字体（能正常显示中文）。体验比 Windows 自带的 cmd 好很多。
2. Use Windows' default console window：使用 Windows 自带的 cmd 窗口。缺点是默认字体显示中文有问题，窗口不能自由调整大小。

这个界面是设置 git pull 命令的默认行为。

1. Fast-forward or merge（默认选中）：快进合并或创建合并提交。这是最安全、最通用的默认设置。
2. Rebase：变基。适合熟悉 Git 且需要干净提交历史的用户，新手不推荐。
3. Only ever fast-forward：仅允许快进合并。新手使用时容易遇到合并失败的问题，不推荐。

这个界面是选择 Git 的凭证助手。

1. Git Credential Manager（默认选中）：官方推荐的跨平台凭证管理工具，能和 Windows 系统的「凭据管理器」深度集成。后续用 Git 拉取或推送代码时，它会自动读取保存的凭证。
2. None：不使用任何凭证助手。每次连接远程仓库都需要手动输入账号密码，操作繁琐且不安全，不推荐。

选项说明：

1. Enable file system caching（已勾选）：开启文件系统缓存，能显著提升 Git 操作的性能。默认勾选是最优选择。
2. Enable symbolic links（未勾选）：启用符号链接功能。对于普通用户和搭建 Hexo 博客的场景来说完全用不到，保持不勾选是正确的。

安装完成。

1.2.3 配置你的 GitHub 用户名和邮箱

在桌面空白处点击右键 → 选择 Git Bash Here（这是最方便的打开方式）。

在打开的 Git Bash 窗口里，输入以下两行命令（记得把内容换成你自己的）：

# 替换成你的 GitHub 用户名
git config --global user.name "你的 GitHub 用户名"
# 替换成你 GitHub 绑定的邮箱
git config --global user.email "你的 GitHub 邮箱@xxx.com"

验证配置是否成功：输入这条命令查看已配置的信息：

git config --global --list

验证 Git 安装是否正常：输入这条命令，查看 Git 版本：

git --version

2. 第二步：Hexo 安装与初始化

前置准备：检查必备工具（已装 Git/Node.js 可直接跳）

Hexo 依赖Git和Node.js，必须先装且能正常使用，验证步骤：

1. 打开 CMD/PowerShell，输入 git --version，回车→显示版本号（如 git version 2.52.0.windows.1）= Git 正常
2. 继续输入 node -v，回车→显示版本号（如 v18.18.2）= Node.js 正常
3. 继续输入 npm -v，回车→显示版本号（如 9.8.1）= npm 包管理器正常（npm 是安装 Node.js 时自动附带的，无需单独装）

2.1 全局安装 Hexo 核心工具

1. 保持 CMD/PowerShell 打开，直接复制以下命令，粘贴后回车：

npm install -g hexo-cli

2. 等待安装完成（屏幕滚动文字，最后无红色报错即成功）
3. 验证安装：输入 hexo -v，回车→显示 Hexo 版本号（如 hexo-cli: 4.3.0）= Hexo 安装成功

2.2 创建 Hexo 博客文件夹并初始化

2.2.1 选一个存放博客的位置（建议非中文 / 无空格路径）

比如：在D 盘新建一个文件夹，命名为 HexoBlog（右键→新建→文件夹，命名为 HexoBlog），路径为 D:\HexoBlog

2.2.2 进入该文件夹（CMD/PowerShell 中切换路径）

1. 在 CMD 中输入以下命令，回车→切换到 D 盘：

D:

2. 继续输入以下命令，回车→进入 HexoBlog 文件夹：

cd HexoBlog

（验证：输入 dir，回车→能看到文件夹内内容（目前为空），即路径切换成功）

2.2.3 初始化 Hexo 博客（核心命令）

在当前 D:\HexoBlog 路径下，复制以下命令粘贴回车：

hexo init

1. 等待初始化完成（最后显示「Start blogging with Hexo!」即成功）
2. 初始化完成后，自动安装依赖：无需额外操作，Hexo 会自动执行 npm install，等待即可

2.3 本地测试 Hexo 博客（关键！验证是否初始化成功）

初始化后，在同一文件夹路径（D:\HexoBlog）下，依次执行以下 2 个命令，启动本地博客预览：

2.3.1 生成静态博客文件

复制命令粘贴回车：

hexo g

（g是 generate 的简写，生成博客所需的静态 HTML 文件，无报错即成功）

2.3.2 启动本地预览服务器

复制命令粘贴回车：

hexo s

（s是 server 的简写，启动本地服务器，最后显示「Hexo is running at http://localhost:4000/ Press Ctrl+C to stop.」即成功）

2.3.3 访问本地博客（验证最终效果）

打开任意浏览器（Chrome/Edge/360），在地址栏输入：http://localhost:4000，回车→看到Hexo 默认博客页面（有 Hello World 文章、分类 / 标签侧边栏）= 安装 + 初始化全部成功！

2.3.4 关闭本地服务器

测试完成后，回到 CMD/PowerShell，按键盘Ctrl+C，回车→即可停止服务器，恢复命令输入。

注意：需要测试完成之后才能关闭命令行窗口！！！

重要补充：新手必记的 3 个常用简写命令

2.3.5 常见小问题解决（新手踩坑必备）

1. 执行 hexo s 后，浏览器访问 http://localhost:4000 打不开→检查 CMD 是否显示服务器启动成功，关闭浏览器重新访问，或换个浏览器
2. 命令执行出现红色报错→先执行 hexo c 清理，再重新执行 hexo g 和 hexo s
3. 初始化时提示「文件夹非空」→确保 HexoBlog 文件夹是新建的空文件夹，无任何其他文件 / 子文件夹

2.3.6 最终成果

你的 D:\HexoBlog 文件夹内会出现 Hexo 默认目录结构，核心文件夹：

• source：存放你的博客文章（.md 格式）
• themes：存放博客主题（后续换主题用）
• public：生成的静态博客文件（部署到服务器时用）

3. 第三步：配置 Hexo 基础信息

这一步是Hexo 博客的核心配置环节，修改的是 Hexo 根目录下的 _config.yml 文件。

用 VS Code 打开 hexo-blog 文件夹，找到根目录的 _config.yml 文件（这是 Hexo 的核心配置文件），修改以下内容：

1. 站点基础配置

# Site title: 我的博客
# 博客标题
subtitle: 记录技术学习与思考
# 副标题
description: 专注技术入门与实战
# 博客描述（SEO 用）
author: 你的名字
# 作者名
language: zh-CN
# 语言设置为中文
timezone: Asia/Shanghai
# 时区设置为上海

2. 部署配置（关键！要和 GitHub 关联）

在文件末尾找到 Deployment 部分，修改为：

# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: git
  repo: [email protected]:你的 GitHub 用户名/你的 GitHub 用户名.github.io.git
  branch: gh-pages

• repo 是你的 GitHub 仓库地址（必须用 SSH 格式，后面会教你配置 SSH 密钥）
• branch 固定为 gh-pages（GitHub Pages 会从这个分支拉取静态文件）

改好后，执行 hexo g -d（生成静态文件 + 部署）命令，Hexo 会自动把本地的博客文件推到你 GitHub 的 用户名.github.io 仓库的 gh-pages 分支，之后别人就能通过 https://你的 GitHub 用户名.github.io 访问你的博客了。

4. 第四步：写第一篇博客文章

4.1 新建博客文章

打开终端（Windows 用 CMD / 终端、Mac 用 Terminal），切换到你的 Hexo 项目文件夹路径，执行命令：

hexo new "我用 NumPy 实现了 KNN 算法"
# 新建一篇标题为'我用 NumPy 实现了 KNN 算法'的文章

✅ 效果：文章会以 Markdown 格式（.md 文件） 生成在项目的 source/_posts 文件夹中。

4.2 编辑博客内容

在 VS Code 中打开 source/_posts 文件夹，找到刚生成的 我用 NumPy 实现了 KNN 算法.md 文件，用 Markdown 语法编辑内容（支持标题、代码块、图片等）。

示例（Markdown 内容）：

# 我用 NumPy 实现了 KNN 算法
今天分享如何用 NumPy 手写 KNN 分类算法：

## 1. 核心原理
KNN 是基于'近邻投票'的分类算法...

## 2. 代码实现
```python
import numpy as np

def knn_predict(X_train, y_train, X_test, k=3):
    # 实现逻辑 pass

### 4.3 生成静态文件

编辑完成后，在终端执行命令，将 Markdown 文章生成浏览器可访问的静态 HTML 文件：

```bash
hexo generate
# 简写：hexo g

✅ 效果：生成的静态文件会存放在项目的 public 文件夹中。

5. 第五步：部署到 GitHub Pages

这一步需结合 GitHub 仓库、SSH 密钥配置，确保博客推送到 GitHub 并在线可访问：

5.1 创建 GitHub 专属仓库（必须严格命名）

1. 登录你的 GitHub 账号，点击右上角「+」→「New repository」；
2. 填写仓库信息（其他选项保持默认，不勾选）：
   • Repository name：必须填 你的 GitHub 用户名.github.io（与账号名完全一致，错 1 个字符都不行）；
   • Visibility：选择「Public」（公共仓库，GitHub Pages 对公共仓库免费）；
3. 点击「Create repository」，仓库创建完成。

5.2 配置 SSH 密钥（避免每次部署输密码）

Windows 系统需额外执行「启用 SSH 代理 + 加载私钥」，Mac/Linux 可跳过这部分：

1. 复制公钥到 GitHub：
   • Windows：打开 C:\Users\你的系统用户名\.ssh\ 文件夹，用记事本打开 id_ed25519.pub，全选复制内容；
   • Mac/Linux：终端执行 cat ~/.ssh/id_ed25519.pub，复制输出内容；
   • 登录 GitHub→点击头像→「Settings」→左侧「SSH and GPG keys」→「New SSH key」：
     • Title 填任意名称（比如 我的笔记本）；
     • Key 框粘贴刚才复制的公钥内容；
     • 点击「Add SSH key」，输入 GitHub 密码确认。

Windows 系统：启用并启动 SSH 代理 + 加载私钥：在管理员 CMD 中执行（解决权限问题）：

sc config ssh-agent start= auto
net start ssh-agent
ssh-add C:\Users\你的系统用户名\.ssh\id_ed25519

生成 SSH 密钥：打开终端（管理员身份运行 CMD），执行命令（替换为你的 GitHub 绑定邮箱）：

ssh-keygen -t ed25519 -C "你的 GitHub 绑定邮箱"

连续按 3 次回车（默认生成路径：C:\Users\你的系统用户名\.ssh\）。

5.3 安装 Hexo 部署插件

在终端的 Hexo 项目路径下，执行命令（安装 Git 部署插件）：

npm install hexo-deployer-git --save

5.4 一键部署博客到 GitHub

在终端的 Hexo 项目路径下，执行清理缓存 + 生成静态文件 + 部署的合并命令（避免旧文件残留）：

hexo clean && hexo generate && hexo deploy
# 简写：hexo c && hexo g && hexo d

✅ 部署成功标志：终端最后显示 Deploy done: git。

5.5 开启 GitHub Pages（让博客在线可访问）

1. 进入你的 GitHub 仓库→点击顶部「Settings」→左侧菜单栏「Pages」；
2. 在「Source」模块中，点击「Branch」下拉框，选择 gh-pages 分支；
3. 点击「Save」，页面会显示 'Your site is published at https:// 你的 GitHub 用户名.github.io'。

5.6 访问你的在线博客

打开浏览器，输入地址：

https://你的 GitHub 用户名.github.io

✅ 首次访问需等待 10-30 分钟（GitHub 解析 DNS / 同步 CDN），之后刷新即可正常访问。

后续更新博客的极简步骤

每次写新文章 / 修改内容后，仅需在终端执行：

hexo new "新文章标题" # 新建文章→编辑内容
hexo c && hexo g && hexo d # 一键部署更新