1. 为什么我最终选了 Hexo 加 GitHub 这套组合
1.1 从"能写就行"到"长期可维护"的选型逻辑
我最早写东西是直接扔在某个在线文档里的，改起来方便，但时间一长问题就来了：排版乱、找不到历史版本、想加个自定义样式基本没戏。后来陆续试过几种方案，最后稳定在 Hexo 加 GitHub 这套组合上，用了挺长时间，中间也帮身边几个朋友搭过，踩的坑基本都踩过一遍了。
先说清楚这套东西到底是什么。Hexo 是一个基于 Node.js 的静态博客生成框架，你写 Markdown，它负责把 Markdown 渲染成一套完整的 HTML 静态页面。GitHub 在这里承担两个角色：一是代码和文章的版本托管仓库，二是通过它自带的 Pages 功能把生成的静态页面免费发布到公网。整套流程下来，你不需要买服务器、不需要配数据库、不需要管后端进程，写完了推一下，几分钟后线上就能看到。
它能解决的问题很明确：低成本、零运维、完全掌控内容和样式。适合谁呢？我觉得三类人最合适。第一类是程序员或者技术写作者，本来就用 Markdown 记笔记，迁移成本几乎为零；第二类是想长期维护个人内容、又不想被平台规则和广告绑架的人；第三类是想顺便练一下 Git 和前端构建流程的新手，这套东西是个很好的练手项目，但又不至于复杂到劝退。
不适合谁也得说清楚。如果你完全不想碰命令行、不想理解任何构建概念，那这套方案会让你很痛苦，不如直接用现成的在线写作平台。如果你需要评论、搜索、会员这类强交互功能，静态博客做起来会比较绕，得靠第三方服务拼凑。所以选型这件事，先想清楚自己要的是"省心"还是"可控"，Hexo 加 GitHub 明显是偏后者的。
1.2 静态生成和动态博客的本质差别
很多人一开始不理解"静态"两个字意味着什么，我用一个生活化的类比解释一下。动态博客（比如传统的服务端博客系统）就像一家餐厅，你每次点菜，后厨现做，数据库是食材仓库，服务器是厨房。好处是能根据你的要求现做各种菜，坏处是厨房得一直开着，食材得一直备着，人多了还会排队。
静态博客则像提前做好的便当，文章在你自己电脑上就已经"做熟"了，生成一堆 HTML 文件，发布出去就是现成的。访客来了直接拿走，不需要后厨现做。所以它快、稳、便宜，几乎不会被流量打垮。代价是"现做"的能力弱，比如实时评论、个性化推荐这些就得靠外部服务补。
理解了这一点，你就能明白为什么 Hexo 的工作流是"本地生成、推送发布"，而不是"服务器实时渲染"。也就能理解为什么每次改完文章都要重新生成一次——因为便当得重新做一遍才能更新。这个心智模型建立起来之后，后面所有操作都会顺理成章。
1.3 整体架构拆解：三层结构各司其职
我把这套博客拆成三层来看，理解起来会清晰很多。
第一层是内容层，也就是你写的 Markdown 源文件，放在source/_posts目录下。这是你真正要长期积累的资产，格式简单、纯文本、不怕平台倒闭。
第二层是生成层，Hexo 读取配置、主题、文章，把它们编译成public目录下的一堆静态文件。这一层是"构建"，发生在你本地。
第三层是发布层，把public里的产物推到 GitHub 仓库，由 Pages 服务对外提供访问。这一层是"托管"，发生在云端。
三层之间是单向流动的：内容变→重新生成→重新发布。搞清楚了这条链路，出问题的时候你就能快速定位是哪一层出了毛病，而不是一脸懵地到处乱试。
2. 动手前的环境准备与关键决策
2.1 Node.js 和 Git 的安装要点
Hexo 跑在 Node.js 上，所以第一步是装 Node。我建议直接去 Node 官网下 LTS（长期支持）版本，不要追最新的尝鲜版。原因很简单，Hexo 和很多主题、插件对 Node 版本有兼容要求，LTS 版本经过大量验证，出问题的概率最低。写这篇文章的时候，Node 18 和 Node 20 都是比较稳的选择。
装完之后验证一下，打开终端输入：
node -v npm -v两条命令都能正常输出版本号，说明装好了。这里有个新手常踩的坑：Windows 上如果之前装过旧版本，可能出现版本冲突，建议先用系统自带的卸载程序清干净再装新的。Mac 用户如果用 Homebrew，注意别和官网安装包混用，容易路径打架。
Git 的安装相对简单，官网下载对应系统版本一路下一步即可。装完同样验证：
git --versionGit 还需要配置一下身份信息，这个信息会记录在每次提交里：
git config --global user.name "你的名字" git config --global user.email "你的邮箱"注意：这里的邮箱建议和你后面注册的代码托管平台账号邮箱保持一致，这样提交记录才能正确归属到你名下。
2.2 包管理器的选择：npm 还是别的
Node 自带 npm，开箱即用，对新手最友好。但如果你在国内网络环境下觉得装包慢，可以换成淘宝镜像源加速：
npm config set registry https://registry.npmmirror.com这条命令只是把下载源换成国内镜像，装包速度会明显提升。也有人推荐 pnpm 或 yarn，它们确实在依赖管理和速度上有优势，但对刚上手的人来说，多一层工具就多一层学习成本。我的建议是：第一次搭就用 npm，等这套流程跑通了、觉得有必要再换。
2.3 仓库类型的决策：两种主流方案对比
这是整个搭建过程中最关键的一个决策点，很多人卡在这里。用 GitHub Pages 发布博客，有两种主流做法，我做个对比。
| 方案 | 仓库结构 | 优点 | 缺点 |
|---|---|---|---|
| 方案A：源码与产物分离 | 一个仓库存源码，另一个仓库存生成的静态文件 | 结构清晰，源码和产物互不干扰 | 需要维护两个仓库，配置稍复杂 |
| 方案B：单仓库双分支 | 同一仓库，一个分支存源码，另一个分支存产物 | 只维护一个仓库，管理集中 | 分支切换时容易搞混，新手易出错 |
我个人的选择是方案A，也就是建两个仓库。原因很实际：源码仓库是你要天天打交道的，产物仓库基本是自动推送、不用管。分开之后，你在源码仓库里怎么折腾都不会影响线上，心理负担小。而且万一产物仓库出问题，重新生成推一次就好，源码永远安全。
具体来说，源码仓库可以叫blog-source之类的名字，产物仓库的命名有讲究——如果你想让访问地址是你的用户名.github.io这种根路径形式，产物仓库必须命名为你的用户名.github.io。这个命名规则是硬性的，写错了访问不了。
2.4 访问地址的两种形态与取舍
顺带把访问地址这件事讲透。GitHub Pages 给你的地址有两种形态。
一种是用户主页型，地址是https://你的用户名.github.io，对应的是那个特殊命名的仓库。这种地址最干净，适合当个人主站。
另一种是项目页型，地址是https://你的用户名.github.io/仓库名，任何仓库都能开启，但地址里会多一段仓库名。
如果你用项目页型，Hexo 配置里有个url和root需要对应调整，否则会出现样式加载不出来、图片 404 的问题。这个坑后面会详细讲。我的建议是，如果打算长期做，直接用用户主页型，省去路径前缀的麻烦。
3. Hexo 初始化与核心配置实操
3.1 安装 Hexo 脚手架并初始化项目
环境齐了就可以装 Hexo 的命令行工具了。全局装一次：
npm install -g hexo-cli装完验证：
hexo -v能看到版本信息就对了。接下来找个你想放项目的目录，执行初始化：
hexo init my-blog cd my-blog npm install第一行创建了一个叫my-blog的文件夹并生成基础结构，第二行进入这个目录，第三行安装项目依赖。这三步做完，一个能跑的博客雏形就有了。
初始化完成后，目录结构大概是这样：
source/_posts：放你的 Markdown 文章themes：放主题_config.yml：主配置文件scaffolds：新建文章的模板public：生成后的静态文件（首次生成后才出现）
先本地跑起来看看效果：
hexo server然后浏览器打开http://localhost:4000，能看到默认页面就说明成功了。这个本地预览服务很实用，改完东西刷新就能看，不用每次都推线上。
3.2 主配置文件逐项拆解
_config.yml是整个博客的大脑，我挑几个必须改的讲。
站点信息部分：
title: 我的博客 subtitle: 记录与分享 description: 一个用来沉淀内容的地方 author: 你的名字 language: zh-CN timezone: Asia/Shanghailanguage设成zh-CN很重要，否则主题里的"""上一篇"这些文案会是英文。timezone设对，文章时间才不会错乱。
网址配置部分，这是最容易出错的地方：
url: https://你的用户名.github.io root: / permalink: :year/:month/:day/:title/如果你用的是用户主页型仓库，root保持/就行。如果用的是项目页型，url要写成https://你的用户名.github.io/仓库名，root要写成/仓库名/。这两个必须匹配，否则线上样式全丢。
permalink决定文章链接的格式。默认是按年月日加标题，好处是清晰、有层次。但如果你文章标题里有中文，链接里会出现一长串编码，不太好看。可以在新建文章时手动指定英文文件名，或者把 permalink 改成:title/这种更短的格式。这个看个人偏好，没有绝对对错。
部署配置部分，先留空，等仓库建好再填。
3.3 主题的挑选与安装方式
默认主题能用但比较朴素，大多数人会换一个。Hexo 主题生态很丰富，挑主题我建议看三点：更新是否活跃、文档是否完整、是否响应式（手机上看是否正常）。
安装主题有两种常见方式。一种是把主题文件直接下载放进themes目录，另一种是用 Git 子模块的方式引入。我更推荐后者，因为主题作者更新时，你一条命令就能同步，不用手动覆盖。
以子模块方式为例：
git submodule add 主题仓库地址 themes/主题名装完在_config.yml里把theme字段改成主题名即可。这里有个细节：很多主题有自己的配置文件，通常叫_config.主题名.yml，放在博客根目录。这样升级主题时你的个性化配置不会被覆盖，这个设计很贴心，一定要用起来。
提示：换主题后如果页面样式错乱，先执行一次
hexo clean清缓存再重新生成，八成能解决。
3.4 写第一篇文章与常用命令
新建文章：
hexo new "我的第一篇文章"这会在source/_posts下生成一个 Markdown 文件，头部有一段 front-matter，用来写标题、日期、标签、分类这些元信息。正文就用标准 Markdown 写，标题、列表、代码块、图片都支持。
几个高频命令记一下：
hexo clean # 清理缓存和已生成的静态文件 hexo generate # 生成静态文件，可简写 hexo g hexo server # 本地预览，可简写 hexo s hexo deploy # 部署，可简写 hexo d我个人的习惯是，改完内容先hexo s本地看效果，满意了再hexo clean && hexo g && hexo d一条龙推上去。clean这一步别省，尤其是换了主题或改了配置之后，缓存不清很容易出现"改了没生效"的诡异现象。
4. 部署到 GitHub 的完整流程
4.1 创建仓库与开启 Pages
先在代码托管平台建两个仓库。第一个是源码仓库，随便起名，私有公开都行，我建议私有，因为源码里可能有草稿。第二个是产物仓库，命名必须是你的用户名.github.io这种格式，且必须是公开的（免费账户下 Pages 对私有仓库的支持有限制）。
建好产物仓库后，进仓库设置里找到 Pages 相关选项，把发布来源设成对应分支（通常是main或master的根目录）。设置完保存，平台会给你一个访问地址。
4.2 配置部署插件与参数
Hexo 部署到 Git 仓库靠的是hexo-deployer-git插件，先装：
npm install hexo-deployer-git --save然后在_config.yml里配置：
deploy: type: git repo: https://github.com/你的用户名/你的用户名.github.io.git branch: main这里branch要和你产物仓库的默认分支一致，现在新建仓库默认多是main，老仓库可能是master，写错会推不上去。
4.3 身份认证的两种方式与选择
推送代码需要身份认证，常见两种方式。
一种是 HTTPS 加访问令牌。你需要在平台设置里生成一个令牌，推送时把令牌当密码用。这种方式配置简单，但令牌要妥善保管，泄露了别人就能推你的仓库。
另一种是 SSH 密钥。本地生成一对密钥，把公钥填到平台账号设置里，之后推送免密。这种方式更安全也更省事，长期用推荐这个。
生成密钥的命令：
ssh-keygen -t ed25519 -C "你的邮箱"一路回车，然后把公钥文件的内容复制到平台设置里。验证是否配置成功：
ssh -T git@github.com看到欢迎信息就说明通了。
4.4 一键部署与验证
配置齐了就可以部署了：
hexo clean && hexo generate && hexo deploy部署成功后，等一两分钟，访问你的 Pages 地址，应该就能看到博客了。第一次访问可能有缓存延迟，如果显示 404，先确认仓库设置里的 Pages 来源分支对不对，再确认产物是否真的推上去了。
注意：部署命令执行时如果卡住或报权限错误，九成是认证没配好。先单独测一下
git push能不能成功，把认证问题解决在部署之前。
5. 常见问题排查与避坑经验
5.1 样式丢失、图片 404 的根因
这是最高频的问题，几乎每个用项目页型地址的人都遇到过。现象是页面能打开，但没有任何样式，或者图片全是裂图。
根因就一个：url和root配置和实际访问路径不匹配。如果你访问的是https://用户名.github.io/仓库名，但配置里root写的是/，那么所有资源请求都会指向根路径，自然找不到。
解决办法就是让配置和实际路径对齐：
url: https://你的用户名.github.io/仓库名 root: /仓库名/改完记得hexo clean再重新生成部署。
5.2 部署报错与推送失败的排查顺序
部署失败别慌，按这个顺序排查：
- 先确认
deploy配置里的仓库地址和分支名没写错 - 再确认认证是否有效，单独跑一次
git push测试 - 检查产物仓库是否有保护分支规则挡住了推送
- 看报错信息里有没有明确的权限或网络提示
我整理了一个速查表：
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 部署卡住不动 | 网络或认证问题 | 检查网络，重配认证 |
| 报权限拒绝 | 令牌过期或密钥未配 | 重新生成并配置 |
| 推上去了但页面没变 | 缓存或分支不对 | 清缓存，核对 Pages 来源分支 |
| 页面 404 | 仓库命名或 Pages 未开启 | 核对命名，检查 Pages 设置 |
5.3 中文链接与时间错乱的处理
中文标题生成的文章，默认链接里会出现编码后的字符，又长又难看。两个办法：一是新建文章时手动指定英文文件名，比如hexo new post "标题"之后把文件名改成英文；二是调整permalink格式，用文章的其他属性来生成链接。
时间错乱通常是timezone没设对，或者服务器时区和本地不一致。把timezone明确设成Asia/Shanghai，基本能解决。
5.4 我踩过的几个真实坑
第一个坑是主题配置文件的覆盖问题。早期我直接改主题目录里的配置文件，结果主题一升级，所有个性化设置全没了。后来改用根目录下的独立配置文件，再也没丢过。
第二个坑是草稿和正式文章混在一起。Hexo 支持草稿功能，但草稿默认不会被生成。我有次以为写了没生效，折腾半天才发现是草稿状态。现在我的习惯是，没写完的放草稿，写完的再正式发布。
第三个坑是图片管理。早期我把图片和文章放一起，路径写得乱七八糟。后来统一用一个图床或者固定的资源目录，路径规范了，迁移和备份都省心。
6. 让博客更好用的进阶技巧
6.1 自动化部署：省掉手动推送
每次手动跑三条命令其实挺烦的，可以用持续集成服务自动化。思路是：你把源码推到源码仓库，云端服务自动帮你装依赖、生成、推送到产物仓库。这样你只需要git push源码，剩下的全自动。
配置的核心是一个流水线配置文件，定义好触发条件（比如推送到主分支）、运行环境（Node 版本）、执行步骤（安装、生成、部署）。部署那一步需要用到访问令牌，存在服务的密钥管理里，不要写死在配置文件里。
6.2 备份与迁移：让内容永远安全
静态博客最大的好处就是内容是你自己的纯文本。但前提是你得真的备份好。我的做法是源码仓库本身就是备份，本地再留一份，重要节点打个标签。这样即使换电脑、换平台，把源码拉下来重新装依赖就能恢复，几分钟的事。
迁移到别的托管平台也很简单，因为产物就是一堆静态文件，扔到任何支持静态托管的地方都能跑。这就是"内容自主"的价值，不被任何单一平台绑死。
6.3 内容组织的长期习惯
最后聊点软性的。工具搭好只是开始，能不能长期写下去靠的是习惯。我的经验是：别追求一次写完美，先写出来再改；标签和分类别建太多，够用就行，否则维护成本高；定期回顾旧文，该更新的更新，该归档的归档。
这套 Hexo 加 GitHub 的方案，我用了挺长时间，最大的感受是它把"写作"和"发布"这两件事的干扰降到了最低。你打开编辑器就是写，写完推一下就是发布，中间没有广告、没有弹窗、没有平台规则来打断你。这种纯粹感，是我一直没换方案的原因。如果你也在找一个能长期安放内容的地方，不妨从这套组合开始试试，搭一次的成本，可能一个下午就够了。
