1. 为什么我最终选了 Hexo 而不是其他静态博客方案
1.1 从一次博客迁移说起
三年前我把自己写了两年多的博客从动态系统迁到了静态站点，当时对比过 Hexo、Hugo、Jekyll 这几个主流方案。最后选 Hexo 的原因很朴素：它是我试过的方案里，对前端基础一般的人最友好的一个。Hugo 构建速度确实快得离谱，几千篇文章几秒就编译完，但它的模板语法对没写过 Go template 的人来说上手曲线偏陡；Jekyll 是 GitHub Pages 原生支持的，省事，但本地预览依赖 Ruby 环境，在 Windows 上装依赖经常出各种莫名其妙的编译错误，我身边至少有三个朋友卡在native extension报错那一步就放弃了。
Hexo 基于 Node.js，只要你机器上有 Node 环境，npm install一把梭基本就能跑起来。它的主题生态也成熟，主流的几套主题文档齐全、配置项清晰，改起来不用啃源码。对于“我就想安安静静写文章，不想折腾构建工具”的人来说，这个平衡点找得很准。
1.2 静态博客到底解决了什么问题
先说清楚静态博客和动态博客的本质区别，不然后面很多设计选择你会看不懂。
动态博客（比如各种带后台的 CMS）每次有人访问，服务器都要查数据库、渲染页面、拼 HTML 再返回。好处是发文章点几下后台就行，坏处是服务器得一直开着，有数据库就有被拖库的风险，访问量一上来还得考虑缓存、负载均衡这些破事。
静态博客反过来：文章在本地写成 Markdown，构建工具一次性把所有页面渲染成纯 HTML 文件，部署上去之后服务器只管发文件，不查库、不渲染。带来的直接好处是：
- 快：纯静态文件，CDN 一挂，全球访问都是毫秒级。
- 安全：没有数据库、没有后台登录入口，攻击面几乎为零。
- 便宜甚至免费：托管在 GitHub Pages 这类服务上，一分钱不花。
- 版本可控：文章就是本地的一堆 Markdown 文件，配合 Git 管理，改错了随时回滚。
代价也很明确：没有在线编辑器，发文章得在本地写完再构建部署；评论、搜索这些动态功能需要借助第三方服务。对我来说这些代价完全可以接受，写作本来就是我一个人在本地完成的事。
1.3 Hexo 的工作流长什么样
理解 Hexo 的工作流，后面所有操作你都能对上号。它大概分这么几步：
- 你在
source/_posts/目录下写 Markdown 文章，文件头部带上 front-matter（标题、日期、标签这些元信息）。 - 执行
hexo generate，Hexo 读取所有文章和配置，套用主题模板，在public/目录生成完整的静态站点。 - 执行
hexo deploy，把public/里的内容推送到你配置的托管平台，比如 GitHub Pages。 - 访客访问你的域名，拿到的是托管平台上的静态 HTML。
整个链路里，Hexo 只负责“本地生成”这一段，托管是 GitHub Pages 的事，两者通过 deploy 配置衔接。搞清楚这个分工，后面遇到“为什么部署上去没更新”“为什么样式丢了”这类问题，排查方向就清晰了。
2. 环境准备与 Hexo 初始化实操
2.1 Node.js 与 Git 的安装要点
Hexo 跑在 Node.js 上，所以第一步是装 Node。去 Node 官网下 LTS（长期支持）版本就行，别追最新的 Current 版，LTS 稳定，第三方依赖兼容性也更好。装完之后在终端敲：
node -v npm -v两条命令都能正常输出版本号，说明环境没问题。这里有个坑要提醒：Windows 用户如果之前装过旧版本 Node，最好先卸载干净再装新的，否则可能出现npm命令找不到或者版本错乱的情况。
Git 也是必须的，因为部署环节要靠它把文件推到 GitHub。装完 Git 后配置一下全局身份：
git config --global user.name "你的用户名" git config --global user.email "你的邮箱"这个身份信息会记录在每次提交里，建议和后面 GitHub 账号用的邮箱保持一致，不然提交记录里显示的作者会对不上。
提示：国内网络环境下
npm install有时会很慢，可以临时切换到国内镜像源加速，装完再切回来。命令是npm config set registry https://registry.npmmirror.com，恢复默认用npm config set registry https://registry.npmjs.org。
2.2 安装 Hexo 脚手架并建站
Hexo 的命令行工具建议全局安装：
npm install -g hexo-cli装完之后找个你想放博客的目录，执行初始化：
hexo init my-blog cd my-blog npm installhexo init会拉取一套默认的站点骨架，包括配置文件_config.yml、文章目录source/_posts、默认主题landscape等等。紧接着的npm install是安装站点运行所需的依赖，这一步千万别跳过，很多人初始化完直接hexo s报错，就是因为依赖没装。
初始化完成后目录结构大致是这样：
| 目录/文件 | 作用 |
|---|---|
_config.yml | 站点全局配置，标题、作者、部署方式都在这 |
source/_posts | 存放 Markdown 文章 |
source | 除文章外的静态资源，如图片、关于页 |
themes | 主题目录 |
public | 构建产物，部署时推送的就是它 |
scaffolds | 新建文章的模板 |
2.3 本地预览与第一篇测试文章
先跑起来看看效果：
hexo server默认监听http://localhost:4000，浏览器打开就能看到默认主题的首页。这个命令支持热更新，你改了文章或配置，刷新页面基本就能看到变化，写文章时开着它很方便。
新建一篇文章：
hexo new "我的第一篇博客"Hexo 会在source/_posts下生成一个同名 Markdown 文件，打开它你会看到顶部的 front-matter：
--- title: 我的第一篇博客 date: 2024-01-01 10:00:00 tags: ---title和date是自动填的，tags可以自己加。正文就用 Markdown 写，写完保存，hexo server那边刷新就能看到。
注意：文章文件名建议用英文或拼音，中文文件名在某些主题和部署环境下可能出现 URL 编码问题，导致链接打不开。标题写在 front-matter 里用中文完全没问题。
3. 站点配置与主题定制
3.1_config.yml里必须改的几个地方
默认配置能用，但有几项不改会显得很“模板化”。打开根目录的_config.yml，重点看这几项：
title: 我的博客 subtitle: 记录与分享 description: 一个普通人的技术笔记 author: 你的名字 language: zh-CN timezone: Asia/Shanghailanguage一定要设成zh-CN，否则主题里的“”“上一篇”这些文案会显示成英文。timezone设成你所在时区，不然文章日期可能差几个小时。
还有一项容易被忽略的是url：
url: https://你的用户名.github.io这个地址要和你最终部署的地址一致，因为 Hexo 生成页面时会用它来拼绝对路径。如果这里填错，部署后可能出现 CSS、图片加载不出来的情况——因为浏览器去错误的域名找资源了。
3.2 换一套顺眼的主题
默认的 landscape 主题比较朴素，大多数人会换。Hexo 主题的安装方式通常是进themes目录克隆：
cd themes git clone <主题仓库地址>然后在根目录_config.yml里把theme字段改成主题文件夹的名字：
theme: 主题文件夹名这里有个关键点：主题的配置和站点的配置是分开的。站点配置在根目录_config.yml，主题配置在themes/主题名/_config.yml。很多人改主题配置时改错了文件，改半天没反应，就是这个问题。改主题配置前，建议先把主题自带的_config.yml复制一份备份，或者按主题文档的说明创建一份独立的配置文件，这样以后升级主题不会把你的配置覆盖掉。
3.3 主题配置里值得花时间调的项
以主流主题的通用配置为例，这几项调完博客的观感会提升一大截：
- 导航菜单：把“首页、归档、标签、关于”这些入口配好，读者能快速找到内容。
- 社交链接：填上你的 GitHub、邮箱等，方便别人联系你。
- 代码高亮：选一个配色舒服的高亮方案，技术博客里代码块的可读性很重要。
- 字数统计与阅读时长：开启后文章顶部会显示“本文共 X 字，预计阅读 X 分钟”，对读者很友好。
- 评论系统：静态博客本身没有评论，需要接第三方。选之前先确认该服务在你目标读者所在地区能正常加载。
实操心得：主题配置项很多，别想着一次全调完。我的做法是先只改导航和社交链接，把博客跑通部署上线，之后再慢慢按需调。一次性改太多，出了问题很难定位是哪个配置项引起的。
4. 部署到 GitHub Pages 的完整流程
4.1 创建仓库与命名规则
登录 GitHub，新建一个仓库。这里有个必须遵守的命名规则：如果你想用用户名.github.io这个免费域名，仓库名必须严格是你的用户名.github.io，一个字都不能差。比如用户名是zhangsan，仓库名就得是zhangsan.github.io。
如果你不打算用这个默认域名，而是想用自定义域名，那仓库名可以随便起，比如blog。但为了省事，我建议直接用用户名.github.io这个方案，零配置就能访问。
仓库创建时选 Public（公开），因为 GitHub Pages 的免费托管对私有仓库的支持有限制。博客本来就是给人看的，公开也无所谓。
4.2 安装部署插件
Hexo 默认不带 Git 部署能力，需要装一个插件：
npm install hexo-deployer-git --save这个插件的作用是让hexo deploy命令能把public目录的内容通过 Git 推送到指定仓库。装完之后，在根目录_config.yml末尾配置部署信息：
deploy: type: git repo: https://github.com/你的用户名/你的用户名.github.io.git branch: mainbranch这一项要注意：GitHub 现在默认分支是main，但有些老教程写的是master。你得去仓库页面确认一下你的默认分支到底叫什么，填错了会推送失败或者推上去不生效。
4.3 一键部署与验证
配置好之后，标准的三连命令是：
hexo clean hexo generate hexo deployhexo clean清掉之前的构建缓存，hexo generate重新生成静态文件，hexo deploy推送。这三步可以合并成一条：
hexo clean && hexo g && hexo dg是generate的缩写，d是deploy的缩写，Hexo 的命令都支持简写。
推送过程中会要求你输入 GitHub 的用户名和密码。注意：GitHub 早就不能用账号密码做 Git 操作了，这里密码要填Personal Access Token（个人访问令牌），不是你的登录密码。令牌在 GitHub 设置的开发者选项里生成，生成时勾选repo权限即可。
部署成功后，等一两分钟，访问https://你的用户名.github.io，应该就能看到你的博客了。第一次部署后 GitHub 需要一点时间构建 Pages，如果立刻访问是 404，别慌，等几分钟再刷新。
4.4 部署流程的自动化思路
每次发文章都要手动敲三条命令，时间长了会烦。有两个优化方向：
一是把命令写成一个脚本文件，比如deploy.sh，内容就是那三行，以后双击或执行脚本就行。Windows 用户可以写个.bat文件。
二是用 GitHub Actions 做持续集成：你把 Hexo 源码推到一个仓库，Actions 自动构建并把public推到 Pages 仓库。这样你只需要git push源码，剩下的全自动。不过这套配置对新手来说有点绕，建议先把手动部署跑熟，理解每个环节在干什么，再上自动化。
5. 常见问题排查与避坑经验
5.1 部署后页面 404 或样式丢失
这是最高频的问题，原因通常集中在两处。
页面 404：先确认仓库名是不是严格等于用户名.github.io，再确认_config.yml里的url和实际访问地址一致。如果仓库名是blog这种非默认名，访问地址会变成用户名.github.io/blog，此时url和root配置都要相应调整，否则路径全错。
样式丢失：八成是url配置和实际域名对不上，导致 CSS 的绝对路径指向了错误的地方。改完url后记得hexo clean再重新构建，因为旧的路径信息可能被缓存了。
5.2 部署报错与推送失败
| 报错现象 | 可能原因 | 解决方向 |
|---|---|---|
Permission denied | 令牌权限不足或过期 | 重新生成令牌，勾选 repo 权限 |
failed to push | 远程仓库有本地没有的提交 | 先git pull合并再推 |
deployer not found | 部署插件没装 | 重装hexo-deployer-git |
| 推送成功但页面没变 | 分支填错或缓存 | 确认分支名，清浏览器缓存 |
避坑技巧：部署前养成
hexo clean的习惯。我有一次改了主题配置，部署上去死活不生效，折腾半小时才发现是构建缓存没清，旧文件被推上去了。从那以后clean就成了我的肌肉记忆。
5.3 图片显示不出来
Markdown 里插图片，路径写法很关键。Hexo 默认的资源处理方式下，图片放在source/images/目录，文章里用/images/图片名.jpg这种以斜杠开头的绝对路径引用最稳。用相对路径容易因为文章 URL 结构变化而失效。
如果你想让每篇文章的图片和文章放一起管理，可以在站点配置里开启post_asset_folder: true，这样hexo new时会同时生成一个同名文件夹，图片放进去用相对路径引用即可。但这个功能需要配合特定语法或插件，用之前先看主题文档是否支持。
5.4 写作与维护的长期习惯
最后分享几个我坚持了很久的习惯，能让博客长期维护下去不那么累。
用 Git 管理源码：Hexo 的源码（不含public和node_modules）建议单独建一个仓库管理。这样换电脑时git clone下来npm install就能继续写，文章历史也有完整记录。记得写个.gitignore把node_modules、public、.deploy_git排除掉。
文章命名规范化：文件名用日期加英文短标题，比如2024-01-01-hexo-deploy.md，排序清晰，URL 也干净。
定期备份主题配置：主题升级时配置文件容易被覆盖，把改过的主题配置单独存一份，升级后对照着恢复，能省很多事。
别追求完美再发布：我见过太多人卡在“主题还没调好”“域名还没买”上，结果一篇文章都没发出去。先把内容写出来、部署上线，样式和域名这些都可以后面慢慢优化。博客的核心价值永远是内容，不是主题有多花哨。
这套流程我从第一次搭建到现在，帮朋友复现过不下十次，每次卡壳的地方基本都在上面列的这些点里。把环境装对、配置改准、部署命令跑通，剩下的就是持续写。工具只是载体，真正让博客活起来的是你愿意往里放的东西。
