1. 为什么我最终选择了 Hexo 而不是其他静态博客方案1.1 从折腾 WordPress到回归静态的转变最早写博客的时候我和大多数人一样第一反应是装个 WordPress。买服务器、配数据库、装 PHP 环境、调主题、装插件一套流程走下来少说半天。刚开始还挺有成就感但时间一长问题就来了服务器要续费数据库偶尔抽风插件更新之后主题样式崩了最要命的是每次想写点东西先得等后台加载半天。后来我算了一笔账一年下来服务器成本加上维护时间换来的只是一个访问量并不高的个人站点性价比实在不高。真正让我下决心换方案的是一次服务器到期忘记续费整站数据差点没找回来。那次之后我开始认真研究静态博客这条路。所谓静态博客简单说就是提前把文章编译成纯 HTML、CSS、JS 文件不需要数据库、不需要后端程序浏览器请求什么就返回什么。这种模式的好处非常直接加载快、安全性高、几乎不消耗服务器资源而且所有内容都是纯文本文件天然适合用 Git 做版本管理。在静态博客的众多方案里Hexo、Hugo、Jekyll 是最主流的三个。我最后选了 Hexo原因后面会详细说但核心就一句话它对中文用户友好、生态成熟、上手门槛低而且和 GitHub 的配合几乎是开箱即用。1.2 Hexo、Hugo、Jekyll 三者到底差在哪很多人一上来就纠结选哪个其实这三个工具解决的是同一个问题——把 Markdown 变成网站差别主要在语言、速度和生态上。我整理了一张对比表方便你一眼看清维度HexoHugoJekyll开发语言Node.jsGoRuby编译速度中等极快较慢中文文档丰富一般一般主题数量非常多较多中等上手难度低中中与 GitHub 集成极佳良好原生支持Hugo 的编译速度确实快得离谱几百篇文章几秒钟就搞定但它的模板语法对新手不太友好中文资料也相对少。Jekyll 是 GitHub Pages 原生支持的但它是 Ruby 写的本地环境配置经常让人抓狂尤其是在 Windows 上。Hexo 用的是 Node.js只要你电脑上装过 Node基本就能跑起来而且它的中文社区非常活跃遇到问题搜一下基本都有答案。提示如果你追求极致编译速度、文章数量上千Hugo 更合适如果你想要最省心的中文体验和丰富主题Hexo 是更稳妥的选择。1.3 一键部署到底省了什么标题里说的一键部署很多人以为是点一下按钮就完事。实际上它指的是把本地生成静态文件和推送到 GitHub这两个动作合并成一条命令。传统流程是写完文章运行生成命令然后手动把生成的文件复制到仓库目录再执行 Git 提交和推送。而 Hexo 配合部署插件之后你只需要敲一行命令它会自动完成生成、切换目录、提交、推送的全过程。这个一键的价值不在于省了那几次复制粘贴而在于它把整个发布流程标准化了。你不用担心忘记生成、不用担心推错分支、不用担心漏掉某个文件。对于经常写文章的人来说发布流程越短写作的阻力就越小这才是关键。2. 本地环境搭建那些文档里不会告诉你的细节2.1 Node.js 版本选择与安装的坑Hexo 基于 Node.js所以第一步是装 Node。这里有个很多人踩过的坑直接去官网下载最新版。最新版不一定兼容你选的 Hexo 版本和主题尤其是某些老主题在新版 Node 上会报各种奇怪的错。我的建议是使用 LTS长期支持版本比如 Node 18 或 Node 20。安装的时候Windows 用户直接下安装包一路下一步就行Mac 用户可以用包管理器装。装完之后一定要验证node -v npm -v两条命令都能输出版本号说明装好了。如果提示命令未找到多半是环境变量没配好重启一下终端或者重新安装通常能解决。还有一个细节npm 默认的镜像源在国内访问比较慢装依赖的时候经常卡住。可以换成国内镜像源加速npm config set registry https://registry.npmmirror.com这条命令只影响 npm 的下载源不涉及任何其他配置纯粹是为了让依赖装得快一点。2.2 Hexo 的安装与初始化目录结构解读Node 装好之后安装 Hexo 的命令行工具npm install -g hexo-cli这里的-g是全局安装装完之后你在任何目录都能用hexo命令。接着找一个你放项目的目录执行初始化hexo init my-blog cd my-blog npm install初始化完成后你会看到一堆文件和文件夹。很多人装完就急着写文章结果后面遇到问题完全不知道文件在哪。我建议先花两分钟搞清楚目录结构_config.yml全站配置文件标题、作者、部署地址都在这里改。source/存放你的文章源文件source/_posts/就是文章目录。themes/主题目录换主题就是往这里放文件夹。public/生成后的静态文件部署时推送的就是这个目录。scaffolds/新建文章的模板可以自定义默认格式。package.json项目依赖清单。理解这几个目录之后后面无论换主题还是改配置你都知道该动哪个文件。2.3 本地预览为什么必须先跑起来再折腾初始化完成后先别急着改配置直接运行hexo server然后浏览器打开http://localhost:4000能看到默认的 Hello World 页面说明环境没问题。这一步非常重要因为它是你的基准线。后面无论改主题还是改配置只要页面打不开了你都知道是刚才那步改坏了而不是环境本身有问题。我见过太多人一上来就装主题、改配置结果页面白屏然后完全不知道从哪排查。先跑通默认状态再一步步改出问题就回退这是最省时间的做法。3. 写作与内容组织让博客真正能长期维护3.1 新建文章与 Front-matter 的正确写法写文章用这条命令hexo new 我的第一篇文章它会在source/_posts/下生成一个 Markdown 文件。打开后你会看到顶部有一段被---包裹的内容这叫 Front-matter用来声明文章的元信息--- title: 我的第一篇文章 date: 2024-01-01 10:00:00 tags: - 随笔 categories: - 生活 ---这里有几个经验点。第一date最好手动确认一下有时候系统时间不准会导致文章排序错乱。第二tags和categories的区别很多人搞不清分类是树状的、一对多的层级关系标签是扁平的、多对多的关键词。一篇文章通常只属于一个分类但可以有多个标签。第三如果你想让文章不显示在首页可以加一行hidden: true部分主题支持。3.2 图片、附件与资源文件夹的管理写博客绕不开图片。Hexo 默认把图片放在source/images/下然后在文章里用相对路径引用。但文章一多所有图片堆在一个目录里会非常乱。更好的做法是开启资源文件夹功能。在_config.yml里找到post_asset_folder改成true。这样每次新建文章时Hexo 会同时生成一个同名的文件夹你把图片放进去文章里直接写文件名就能引用。配合某些主题的图片插件还能自动处理路径问题。注意开启资源文件夹后引用图片的语法和普通 Markdown 略有不同具体要看主题文档。如果发现图片不显示先检查路径写法。3.3 草稿、置顶与多设备同步的实用技巧有时候文章写了一半不想发布可以用草稿功能hexo new draft 未完成的文章草稿存在source/_drafts/下不会出现在网站上。想发布时用hexo publish draft 未完成的文章把它移到正式文章目录。置顶功能需要主题支持一般是在 Front-matter 里加sticky: 1数字越大越靠前。至于多设备同步这是很多人忽略的问题。因为博客源文件本质就是一堆文本最省心的做法是把整个项目除了node_modules和public推到一个 Git 仓库。换电脑时克隆下来装好依赖就能继续写。这样你的文章、配置、主题全都跟着走不会丢。4. 主题选择与个性化别让博客长得像模板4.1 挑选主题的三个判断标准Hexo 的主题多到挑花眼但选主题不能只看截图好不好看。我的判断标准有三个第一看更新频率。一个两年没更新的主题很可能在新版 Hexo 上出问题。去仓库看最近的提交时间越近越好。第二看文档完整度。好的主题一定有详细的中文配置文档告诉你每个功能怎么开、每个参数什么意思。文档写得含糊的用起来会很痛苦。第三看是否臃肿。有些主题功能堆得特别多加载一堆用不上的脚本拖慢页面速度。个人博客其实不需要太复杂干净、快、能读就行。4.2 主题安装与配置文件的覆盖逻辑安装主题一般是把主题仓库克隆到themes/目录下然后在根目录_config.yml里把theme字段改成主题文件夹名。这里有个关键机制要理解Hexo 的配置是分层的。根目录的_config.yml管全站主题目录下还有一个_config.yml管主题自己的样式和功能。改主题相关的东西要去主题的配置文件里改改根目录那个是没用的。很多人改了半天没反应就是因为改错了文件。更稳妥的做法是使用配置覆盖在根目录建一个_config.主题名.yml把你想改的主题配置写进去。这样主题升级时你的自定义配置不会被覆盖掉。4.3 导航栏、社交链接与页面的增删主题配置里通常有菜单menu和社交social两块。菜单决定导航栏显示哪些页面比如首页、归档、关于。默认可能只有首页和归档你想加关于页面需要先创建hexo new page about这会在source/about/下生成一个index.md你在里面写内容然后在主题配置的 menu 里加上对应项导航栏就会出现。社交链接就是填你的各个平台地址填了才会显示图标。不填的项直接注释掉别留空否则可能出现空图标。5. 部署到 GitHub从手动推送到真正的一键5.1 仓库类型的选择用户页还是项目页在 GitHub 上建仓库时命名方式决定了你的博客地址。有两种用户页仓库名必须是你的用户名.github.io访问地址就是https://你的用户名.github.io。项目页仓库名随便起访问地址是https://你的用户名.github.io/仓库名。个人博客一般选用户页地址更短更干净。但要注意一个账号只能有一个用户页仓库。5.2 安装部署插件与配置 deploy 字段Hexo 本身不带部署功能需要装插件npm install hexo-deployer-git --save然后在根目录_config.yml里配置 deploy 部分deploy: type: git repo: https://github.com/你的用户名/你的用户名.github.io.git branch: main这里branch要和你仓库的默认分支一致。现在 GitHub 默认是main老仓库可能是master填错了会推送失败。5.3 一键部署命令背后的完整流程配置好之后部署就一条命令hexo clean hexo deployhexo clean是清除之前的生成缓存避免旧文件干扰。hexo deploy会自动执行生成、切换到部署目录、提交、推送。这就是标题里说的一键部署。如果你想本地预览和部署一起做可以用hexo clean hexo generate hexo deploy或者简写成hexo g -d。提示第一次部署时Git 会要求你输入 GitHub 的用户名和密码或令牌。现在 GitHub 已经不支持密码推送需要用个人访问令牌。在 GitHub 设置里生成一个令牌权限勾选仓库相关即可然后把它当密码用。5.4 部署失败的常见原因与排查顺序部署失败是最让人头疼的环节。我总结了一个排查顺序按这个顺序基本能定位问题现象可能原因排查方法提示仓库不存在地址写错或权限不足检查 repo 地址和令牌权限推送被拒绝分支名不匹配确认 branch 字段与仓库一致页面 404仓库名不符合规范用户页必须是 用户名.github.io样式丢失路径配置错误检查根目录 url 和 root 字段部署成功但没更新缓存问题执行 hexo clean 后重试其中页面 404和样式丢失最常见。前者多半是仓库命名不对后者通常是_config.yml里的url和root没配对。用户页的root是/项目页的root是/仓库名/。6. 自动化与进阶让发布这件事彻底不用管6.1 用 GitHub Actions 实现推送即发布前面的一键部署还是需要你在本地敲命令。如果你想更进一步做到写完文章推送到源码仓库网站自动更新可以用 GitHub Actions。思路是这样的建两个仓库一个存源码一个存生成的网站。在源码仓库里配置一个工作流每次推送时自动安装依赖、生成静态文件、推送到网站仓库。这样你只需要在本地写文章、提交、推送剩下的全自动完成。工作流的核心步骤大致是检出代码、装 Node、装依赖、执行生成、推送到目标仓库。具体配置需要根据你的仓库结构来写关键是令牌要配好否则推送会失败。6.2 自定义域名与 HTTPS 的配置要点用github.io的地址虽然能用但不够个性。绑定自定义域名需要两步在域名服务商那里添加一条 CNAME 记录指向你的 GitHub 地址然后在仓库设置里填入域名。HTTPS 方面GitHub Pages 现在支持自动签发证书绑定域名后等一会儿勾选强制 HTTPS即可。如果证书一直签发失败多半是 DNS 还没生效等几个小时再试。6.3 备份、迁移与长期维护的建议最后说几个长期维护的经验。第一源码一定要有备份最好就是放在 Git 仓库里这样换电脑、重装系统都不怕。第二主题升级前先备份配置因为升级可能覆盖你的自定义改动。第三定期检查依赖Node 和 Hexo 版本太老可能出兼容问题但也不要盲目追新稳定优先。我自己的习惯是每写几篇文章就提交一次源码部署命令跑完确认网站正常再关电脑。这套流程跑顺之后写博客这件事的阻力就只剩下想不想写了技术层面基本不用再操心。这套方案我从搭建到现在用了挺长时间中间换过主题、改过配置、也遇到过部署失败但整体上它足够稳定、足够省心。如果你也想有一个完全属于自己的写作空间又不想被服务器和数据库折腾Hexo 加 GitHub 这条路值得走一遍。
