鸳鸯蝴蝶派写个人博客这件事，我前前后后折腾过 WordPress、Typecho、还有各种在线写文章的站点，最后留在 Hexo + GitHub Pages 这套组合上没再换过。如果你现在处于“想搭个自己的博客但不知道从哪下手”的状态，这套方案真心值得花一个晚上搞定。Hexo 是一个基于 Node.js 的静态博客框架，GitHub Pages 则是 GitHub 提供的免费网页托管服务，两者配合起来，你只需要负责用 Markdown 写文章，剩下的生成页面、发布上线都由命令完成，托管费用是 0，服务器运维是 0，对于零基础的新手来说，这可能是最不容易劝退的一条路。
我在给身边朋友做技术分享时，发现大多数人卡住的点并不是 Hexo 本身，而是对整个“本地生成到远程部署”的流程缺乏整体概念。所以这篇会从零开始，把每一步为什么要这么做、做了之后会发生什么都说清楚。你不需要有任何 Node.js 或 Git 基础，只要会敲命令、能跟着操作，就能在本地跑起自己的博客，并且部署上线到 GitHub Pages 上，得到一个像 用户名.github.io 这样的专属网址。
1. 先搞清楚这套方案是什么，以及为什么选它
1.1 这套博客系统到底由什么组成
Hexo 和 GitHub Pages 是两样东西：Hexo 负责把 Markdown 格式的文章渲染成一堆静态网页文件（HTML、CSS、JavaScript），GitHub Pages 负责帮你免费托管这些静态文件，让全世界都能通过网址访问。
这里关键要理解“静态网页”这个概念。传统博客如 WordPress，页面内容是动态生成，访问者发一个请求，服务器去数据库里查内容、拼装页面再返回，所以你需要一台一直在跑的后端服务器，还要维护数据库、处理安全补丁。而 Hexo 走的是“预先生成”的路子：你在本地写完文章，执行一行生成命令，它就把整个博客的所有页面全部渲染成静态 HTML 文件，你只需要把这些文件上传到任何一个静态文件托管服务即可。
GitHub Pages 本质上就是一个静态文件托管服务，你上传什么，它就原样显示什么，不涉及任何后端逻辑。这套组合的好处在于：内容在你自己的电脑上，数据完全可控；托管免费，无服务器费用；GitHub 的全球 CDN 让国内访问速度也很不错；即便是几年后回来维护，环境也不复杂，塞进包里就能跑。
1.2 和其他博客方案对比，优势在哪
我对比过几条常见路线，这里直接说结论。
- WordPress：功能最全、插件生态最强，但需要买主机或 VPS，需要处理服务器环境、数据库备份、插件兼容、安全防护，对只想安静写文章的人来说，运维成本太高。
- Typecho：轻量，但同样需要 PHP 环境和服务器，而且主题质量参差不齐，踩坑成本不小。
- 语雀、Notion：人家平台很好，但那是“笔记/文档”而非“博客”，发布、SEO、自定义域名、页面定制都受限，内容也被平台绑定。
- Hugo：同样优秀的静态博客框架，生成速度快，但 Hugo 的模板语法和配置方式对零基础者来说有一定学习曲线，主题资料中文教程相对少。
- Hexo：专为博客场景设计，
hexo new建文章、hexo g生成、hexo d部署，三步循环，主题极其丰富，中文社区活跃，遇到问题基本搜得到答案。
对你来说，如果核心需求是“稳定、免费、有完整的写作体验，同时不想被平台绑架”，Hexo + GitHub Pages 是当下最符合这个描述的组合。它还能绑自定义域名，以后想升级成自己的域名，只需要在 DNS 那里加一条解析，不改任何代码。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 搭建前的本地环境准备
2.1 安装 Node.js 与 Git，版本怎么选
Hexo 依赖 Node.js 运行环境，部署时需要 Git 把生成的静态文件推送到 GitHub，所以这两样必须先装好。Windows 用户直接去 Node.js 官网下载 LTS 版本的安装包，一路下一步即可，macOS 用户建议通过 Homebrew 安装：brew install node git。
Node.js 版本这里多说一句：别追新，选 LTS 版本。LTS 意味着长期维护、稳定，Hexo 对最新 Node 版本的适配经常有滞后，我用过的两个踩坑案例都是因为用了最新版 Node 导致 Hexo 依赖包编译报错。安装完成后，打开终端（Windows 是 PowerShell 或 CMD，macOS 是 Terminal），依次输入下面两条命令验证：
bash复制node -v
npm -v
git --version
三条命令都能输出版本号，说明环境就绪。如果你在 macOS 上第一次用 Git，它会弹窗要求安装 Command Line Tools，按提示装完再验证一次。
2.2 用 npm 安装 Hexo 脚手架
环境就绪后，安装 Hexo 的命令只有一条：
bash复制npm install -g hexo-cli
-g 代表全局安装，这样你在任何一个目录下都能直接使用 hexo 命令。安装过程可能比较慢，npm 默认源在国外，如果卡住超过两分钟，可以把 npm 源切换到国内镜像：
bash复制npm config set registry https://registry.npmmirror.com
切换源后重新执行安装命令，速度会有质的提升。安装完成后执行 hexo version，看到类似 hexo-cli: 4.x.x 的输出，就说明脚手架装好了。
这里有个新手常搞混的概念：hexo-cli 只是脚手架，真正要跑博客主体，还需要在项目目录里执行 npm install 安装项目依赖。所以后续每次初始化新博客，都会出现“全局脚手架 + 本地项目依赖”两层依赖，不要觉得重复，这是 Node.js 项目的标准结构。
3. 初始化博客，选主题，改配置
3.1 用 hexo init 初始化一个干净站点
先在本地建一个目录，专门放博客项目。我的习惯是放在 ~/Workspace/MyBlog 下，你也可以按自己喜欢的位置来。在终端执行：
bash复制hexo init MyBlog
cd MyBlog
npm install
第一条命令会从 GitHub 拉取 Hexo 的官方初始模板，生成整个博客骨架；第二条进入项目目录；第三条安装这个博客所需的全部依赖包。整个过程一般两到三分钟。
npm install 执行完后，用 hexo s（hexo server 的简写）启动本地预览服务，浏览器访问 http://localhost:4000，你会看到一篇默认的 Hello World 文章。到这一步，你的博客骨架已经活了，所有后续操作都在这个项目目录里进行。
本地目录里需要先认识的几个关键文件：
_config.yml：博客的全局配置文件，站点标题、作者、部署地址都在这里改。source/_posts/：文章存放目录，你写的所有 Markdown 文件都在这里。themes/：主题目录，每个主题一个文件夹。public/：生成的静态网页目录，执行hexo generate后才会出现。
3.2 安装一个主题，让博客有点自己的样子
默认主题 Landscape 功能太简单，大多数人都要换一个。Hexo 的主题市场非常丰富，比较大众的选择有 NexT（写作型、文档全）、Fluid（视觉清爽、响应式好）、Butterfly（颜值高、功能丰富）。我的博客用的是 NexT，它的配置文件和 Hexo 主配置相互独立，结构清晰，适合新手理解主题机制。
以 NexT 为例，安装方式是在项目根目录执行：
bash复制git clone https://github.com/theme-next/hexo-theme-next themes/next
然后把 _config.yml 里的 theme 字段从 landscape 改成 next，再重新执行 hexo s 刷新页面。你会发现整个界面都变了，这就是主题的作用。
主题的个性化设置在主题目录下的 _config.yml 里，注意它和根目录的 _config.yml 是两个文件，很多人改了半天没反应，就是因为改错了文件。NexT 的配置文件里能调的内容很多，比较常用的有：
- 菜单栏：首页、分类、标签页面的开关。
- 站点头像：替换成自己的图片。
- 侧栏社交链接：放上你的 GitHub、邮箱。
- 代码块样式：选择高亮风格。
建议第一次只改头像、菜单和站点描述这几个基础项，其他等熟悉了再慢慢调。一次不要大改，改完就刷新预览看效果，这样出了问题能知道是哪一步引起的。
3.3 核心配置文件 _config.yml 要改哪些项
打开根目录的 _config.yml，这里几乎是整个博客的“控制面板”。初次搭建，只需要改下面几个字段：
yaml复制# 站点信息
title: 你的博客标题
subtitle: 一句话副标题
author: 你的名字
language: zh-CN
timezone: Asia/Shanghai
# URL 配置
url: https://你的用户名.github.io
其中 language 和 timezone 两个字段特别容易被忽略。language 不设成 zh-CN，很多主题的中文翻译不会生效，界面可能显示英文；timezone 不设的话，文章的时间戳可能跟你的本地时间差几个小时，发布后文章日期和实际不符。
url 字段要提前想好，因为你创建的 GitHub Pages 仓库名决定了最终的访问地址。如果你的 GitHub 用户名是 zhangsan，那么仓库名必须是 zhangsan.github.io，地址就是 https://zhangsan.github.io。建议在改这一项之前，先去把仓库创建好。
保存配置后，养成习惯：每次修改配置文件，都要重启本地预览服务才能生效。Ctrl + C 停掉，再运行 hexo s。
4. 写第一篇文章并本地预览
4.1 用 hexo new 创建文章，Markdown 怎么排版
创建新文章的命令：
bash复制hexo new "我的第一篇文章"
执行后，source/_posts/ 目录下会生成一个 我的第一篇文章.md 文件。用任意文本编辑器（推荐 VS Code，新手友好）打开，你会看到文章内容最上方有一段用三个短横线包裹的区域，这就是 front-matter，文章的元信息区：
yaml复制---
title: 我的第一篇文章
date: 2024-01-15 10:30:00
tags:
---
写完标题和日期，在下方用 Markdown 语法写正文。Markdown 本身不复杂，掌握几个高频语法就能顺畅记录：
#到######是 1 到 6 级标题**文字**加粗，*文字*斜体- 三个反引号包裹代码块，前后标注语言类型如
```python 插入图片
正文建议每 200 字左右空一行分段，这样渲染出来的阅读体验最好。你不需要把 Markdown 全部学完再动手，写完一篇再查一个语法是最快的学习方式，这个我用了三年博客，常用的也没超过十个语法。
4.2 文章头部信息的几个关键字段
front-matter 看起来不起眼，但字段影响很大，值得认真填：
tags：文章标签，多个标签用列表格式- 标签1分行写。categories：文章分类，一般写一个即可，多级分类用数组写法。date：文章发布日期，默认是创建时间，如果你想发一篇“旧文章”，改这里即可。
一个填写示例：
yaml复制---
title: Hexo + GitHub Pages 零基础搭建博客详细步骤
date: 2024-01-15 10:30:00
tags:
- Hexo
- 博客搭建
categories:
- 技术教程
---
注意 title 字段是文章的显示标题，跟文件名是两回事。文件名建议用英文或拼音，避免 URL 中出现中文编码；标题用中文完全没问题。这一点很多人不知道，早期我都是直接拿中文当文件名，结果部署后文章链接长得像一串乱码，后来统一改成了英文文件名，清爽多了。
4.3 本地预览与调试技巧
写作过程中随时可以执行 hexo clean && hexo generate && hexo server 三连命令来重新生成并启动本地服务。让你一定记住 hexo clean 的原因：Hexo 会缓存生成结果，如果你改了配置文件或者删了文章，不清缓存直接生成，页面可能还是旧状态。hexo clean 就是清空缓存和旧的 public 目录，是排查“改了没反应”问题的第一选择。
本地预览没问题，再进入下一步部署。这是我在流程上强烈建议的顺序：先在本地把文章、配置、主题都调试满意，再上线，避免把半成品推到线上反复改。
5. 部署到 GitHub Pages 的完整流程
5.1 创建 GitHub 仓库，名称决定了你的站点地址
登录 GitHub，点击右上角加号选择 New repository，仓库名填写 你的用户名.github.io，注意用户名必须与你的 GitHub 用户名完全一致。比如我的用户名是 hexowriter，仓库名就是 hexowriter.github.io。如果你填的名字跟用户名不一致，最后生成的访问地址就不是想要的。
仓库可见性选 Public。GitHub Pages 只有 Public 仓库可以免费托管，选 Private 也能建站但需要付费方案。勾选初始化 README 文件与否都可以，一般不用勾，Hexo 部署时会帮你管理里面的内容。创建完仓库后，暂时不需要做任何操作，部署动作全部通过 Hexo 在本地完成。
如果你还没注册 GitHub，这一步先注册账户。注册本身免费，只需要一个邮箱，按照页面引导设置密码和用户名即可。
5.2 安装并配置 hexo-deployer-git
Hexo 默认不带部署插件，需要单独安装。在项目根目录执行：
bash复制npm install hexo-deployer-git --save
安装完成后，打开根目录的 _config.yml，滑到最底部，找到 deploy 配置段，改成如下内容：
yaml复制deploy:
type: git
repo: git@github.com:你的用户名/你的用户名.github.io.git
branch: main
repo 字段是部署目标的仓库地址。新手这里容易困惑的是 HTTPS 地址和 SSH 地址选哪个。我这里直接建议用 SSH 地址，格式是 git@github.com:用户名/仓库名.git。原因是 SSH 方式配置好后免密，以后部署不用反复输密码。如果你用 HTTPS 地址，后续大概率要配置 token，多一层步骤和出错概率。
SSH 是 Git 的安全协议，第一次部署前需要在本地生成一对密钥，公钥放到 GitHub 上建立信任关系。生成及配置命令：
bash复制ssh-keygen -t ed25519 -C "你的邮箱@example.com"
一路回车生成在默认目录。然后查看公钥内容：
bash复制cat ~/.ssh/id_ed25519.pub
复制输出内容，到 GitHub 的 Settings -> SSH and GPG keys 页面，点击 New SSH key，粘贴保存。验证是否配置成功：
bash复制ssh -T git@github.com
如果返回 Hi 你的用户名! You've successfully authenticated 之类的提示，说明 SSH 信任关系建立成功。
5.3 一键部署，以及部署后的验收
配置完成，在项目根目录执行部署命令：
bash复制hexo deploy
或者组合命令一次到位：
bash复制hexo clean && hexo generate && hexo deploy
hexo generate 生成静态页面到 public/，hexo deploy 把 public/ 下的内容推送到 GitHub 仓库。第一次部署需要输入 SSH 密钥的 passphrase（如果生成时设置了），之后就不再需要。
部署完成，浏览器访问 https://你的用户名.github.io，能看到和本地预览完全一致的页面，说明博客已经正式上线。注意首次访问可能因为 DNS 解析延迟，等一两分钟再刷新。
部署后还有一个需要了解的点：GitHub Pages 默认从仓库的 main 分支读取站点文件，这就是上面 branch: main 的原因。Hexo 部署插件会把 public/ 下的内容推送到该分支，而你的 Markdown 源文件依然保存在本地项目目录。所以本地项目目录建议额外用一个 Git 仓库管理，这样源文件和生成的静态文件互不干扰，这是一个非常好的习惯。
6. 常见问题与排查技巧实录
6.1 本地预览起不来，端口被占用怎么办
执行 hexo s 如果提示端口 4000 被占用，有两个解决办法。临时方案是换端口启动：
bash复制hexo s -p 5000
永久方案是找到占用进程杀掉，Windows 下用 netstat -ano | findstr 4000 查看进程 PID，再到任务管理器结束进程；macOS/Linux 用 lsof -i :4000 查看 PID，再 kill -9 PID。我踩过几次这种坑，基本都是后台残留的旧 Node 进程占着端口，直接换端口启动最省事。
6.2 部署成功但页面 404 或显示空白
这一条是出现频率最高的问题。部署命令执行成功，仓库里也能看到文件，但访问 用户名.github.io 却 404。绝大多数情况是仓库名和用户名不匹配，你创建了 abc.github.io，但用户名是 abc，这两个必须一致。还有一种情况是刚部署完，GitHub 页面解析还没完成，等五分钟刷新再试。
另一个容易忽略的点：如果你之前勾选了创建 README，仓库里会混入一个 README 文件，Hexo 部署时可能会报“远端有未合并的分支”错误。解决办法是部署前到 GitHub 页面删掉仓库里的 README 文件，或者用 git pull 整合一次。
6.3 页面样式丢失，图片不显示
部署后页面能打开，但样式全乱、图片裂了，这个问题几乎都出在 _config.yml 的 url 配置上。如果本地预览时 url 写成 http://localhost:4000 忘了改，生成的页面里所有静态资源路径都指向本地地址，部署到线上自然找不到。把 url 改成 https://你的用户名.github.io，执行 hexo clean && hexo generate && hexo deploy 重新部署即可。
图片显示还有一个注意事项：文章配图建议放在 source/images/ 目录下，文章里这样引用：
markdown复制
不要用本地绝对路径如 C:\Users\...\图片.png，部署后绝对路径不存在，图片必挂。用相对路径或站点根路径，是最稳妥的方式。
6.4 部署命令报错：spawn failed
hexo deploy 报 spawn failed ENOENT 这个错误，原因往往是 SSH 密钥没有正确配置，或 Git 身份信息缺失。先执行：
bash复制git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"
然后再执行部署。如果还报同样的错，回到上面 SSH 配置环节，检查公钥是否已添加到 GitHub。为了自我排查，你可以试试直接在项目目录下执行 git ls-remote git@github.com:用户名/用户名.github.io.git，如果能列出分支信息，说明 SSH 是通的，问题在别处；如果报权限错误，问题就在密钥上。
6.5 写文章时几个容易忽略的细节
最后分享几个我写了三年博客总结的实操心得，都踩过坑才换来的。
- 文件名用英文和数字，不要用中文，避免 URL 编码问题。
- 文章里的反引号、代码块不要用全角符号，Markdown 里全角符号会导致格式错乱。
- 每次部署前强制养成
hexo clean的习惯，不清缓存部署，偶发遇到旧文件残留。 - 图片先压缩再放，一张 5MB 的图片会把页面加载速度拖垮，推荐用 tinypng 压缩后再传入本地。
- 写长文时随手保存，Hexo 和编辑器都没有自动保存机制，丢了只能重写。
按照这个流程走下来，从零到上线，通常一个小时内就能完成。我第一次搭建花了整整一晚上，大部分时间耗在理解“为什么要这样做”上，现在工具链熟练了，新起一个博客从环境到部署只需要二十分钟左右。这套方案还有一个好处是迁移成本极低——所有内容都是 Markdown 文件，换电脑后重新 clone 项目，装一遍依赖就能接着写，博客的数据完全掌握在自己手里。后续你还可以尝试绑定自定义域名、配置自动部署、接入评论系统，这些都是基于这个基础往上叠加的玩法，先把核心跑通，其他都是锦上添花。