1. 为什么我最终选择了 Hexo 而不是其他静态博客工具1.1 从“写文章”这件事本身出发的选型逻辑我最早写博客用的是在线平台好处是注册就能写坏处是数据不在自己手里页面样式改不动广告还时不时冒出来。后来陆续试过几种自建方案最终稳定在 Hexo 上原因其实很朴素它把“写作”和“发布”这两件事拆得足够干净。Hexo 是一个基于 Node.js 的静态博客生成器。你写的每一篇文章都是本地的一个 Markdown 文件执行一条命令它就把这些 Markdown 渲染成一套完整的 HTML 静态站点然后你把生成出来的静态文件推到托管平台博客就上线了。整个过程没有数据库、没有后端服务、没有运行时依赖服务器只负责把 HTML 文件发出去。这个特性带来的直接好处有三个。第一是快静态页面没有数据库查询和模板实时渲染打开速度几乎只取决于网络和文件大小。第二是稳没有后端就没有后端漏洞也不存在数据库连接失败、服务进程挂掉这类问题。第三是可迁移你的全部资产就是一堆 Markdown 文件和一份配置文件换电脑、换托管平台、甚至换生成器成本都很低。那为什么不是 Jekyll、Hugo 或者别的我自己的判断标准是这样的Jekyll 依赖 Ruby 环境在部分系统上装依赖容易卡住Hugo 用 Go 编写构建速度确实快得离谱但主题生态和中文资料相对 Hexo 少一些Hexo 基于 Node.js前端开发者基本人手一个 Node 环境主题数量多中文社区活跃遇到问题搜得到答案。对于一个以“长期稳定写下去”为目标的个人博客来说Hexo 的综合体验最均衡。1.2 静态博客和动态博客的本质区别很多人一开始会纠结“静态博客是不是功能很弱”。这里需要把概念理清楚。动态博客比如传统的 WordPress是每次有人访问服务器现场查数据库、拼页面再返回静态博客是提前把所有页面生成好访问时直接返回现成文件。打个比方动态博客像餐厅现点现做灵活但高峰期慢静态博客像提前备好的便当拿出来就能吃速度极快。代价是评论、搜索、访问统计这些“需要实时交互”的功能静态博客本身不提供得靠第三方服务或者客户端脚本来补。对个人博客来说这个取舍非常划算。绝大多数个人博客的核心诉求就是“把文章稳定地展示出来”评论和统计属于锦上添花。而且这些功能现在都有成熟的第三方方案挂一段脚本就能用完全不影响静态站点的整体架构。1.3 一键部署到底“一键”在哪里标题里说的“在 GitHub 上一键部署”本质是利用 GitHub 提供的静态页面托管能力配合自动化构建流程把“本地生成 手动上传”这两步合并成“推送代码后自动完成”。传统流程是本地写完文章执行生成命令得到 public 目录再用工具把 public 目录的内容推送到托管分支。这个流程每次都要重复容易忘、容易出错。而自动化流程是你把源码推送到仓库的某个分支托管平台检测到推送后自动帮你执行生成命令再把结果发布出去。你只需要做一件事——推送源码。这就是“一键”的真正含义把重复劳动交给自动化人只负责创作。下面我会把整套流程从环境准备到自动化部署完整拆一遍包括我踩过的坑和参数选择的理由。2. 环境准备与 Hexo 初始化实操2.1 Node.js 与 Git 的安装要点Hexo 运行在 Node.js 之上所以第一步是装 Node。版本选择上我建议用当前主流的 LTS长期支持版本不要追最新的实验版。原因很简单Hexo 及其插件对 Node 版本有一定兼容范围太新的版本偶尔会出现依赖编译失败的问题而 LTS 版本经过大量用户验证最稳。安装方式上Windows 用户直接去 Node.js 官网下载安装包一路下一步即可安装时会自动带上包管理工具 npm。macOS 用户如果装了包管理器一条命令就能搞定没装的话也可以用官网安装包。安装完成后打开终端验证node -v npm -v两条命令都能输出版本号说明环境正常。如果提示“命令未找到”多半是安装时没勾选“添加到系统路径”重装一次并勾选即可。Git 同样需要安装因为后面要把代码推送到远程仓库。装完后配置一下身份信息这两条配置会记录在每次提交里git config --global user.name 你的名字 git config --global user.email 你的邮箱注意这里的邮箱建议和你后面注册的代码托管平台账号邮箱保持一致否则提交记录可能无法正确归属到你名下。2.2 安装 Hexo 命令行工具环境就绪后全局安装 Hexo 的命令行工具npm install -g hexo-cli装完后执行hexo -v能看到版本信息就说明成功了。这里有个常见坑如果你用的是 macOS 或 Linux全局安装可能因为权限问题报错。不要直接用管理员权限去装那样容易把全局目录的权限搞乱。正确做法是配置 npm 的全局安装目录到用户目录下或者使用 Node 版本管理工具来管理环境。Windows 用户一般不会遇到这个问题。2.3 初始化博客项目与目录结构解读找一个你习惯放代码的目录执行初始化hexo init my-blog cd my-blog npm install第一条命令会创建一个名为 my-blog 的文件夹并生成基础骨架第二条命令安装项目依赖。初始化完成后你会看到这样一套目录结构理解每个目录的作用非常关键目录/文件作用说明source/_posts存放所有文章 Markdown 文件这是你日常打交道最多的地方source其他子目录存放页面、图片等静态资源themes存放主题每个主题一个子文件夹scaffolds新建文章时的模板可自定义默认字段_config.yml站点主配置文件站点标题、作者、部署方式都在这里public生成命令执行后输出的静态文件目录部署的就是它package.json项目依赖清单我特别想强调source/_posts和_config.yml这两个位置。前者是你的内容资产后者是你的站点行为控制中心。把这两个地方摸熟Hexo 就算入门了。2.4 本地预览先跑起来再谈美化初始化完成后先别急着改配置直接启动本地服务看看默认效果hexo server终端会提示服务运行在本地某个端口默认 4000。浏览器打开对应地址能看到一篇默认的 Hello World 文章说明整条链路是通的。这个本地服务支持热更新你改了文章或配置刷新页面就能看到变化不用反复重启。实操心得本地预览时如果页面样式错乱先检查是不是浏览器缓存。强制刷新清缓存刷新往往能解决大部分“看起来没生效”的问题。3. 站点配置与主题定制的核心细节3.1 主配置文件里必须改的几个参数打开根目录的_config.yml参数很多但真正影响站点基本面貌的就那么几个。我按重要性排一下title: 我的博客 # 站点标题显示在浏览器标签和页头 subtitle: 记录与思考 # 副标题 description: 一个普通人的技术笔记 # 站点描述影响搜索引擎摘要 author: 你的名字 # 作者名 language: zh-CN # 语言中文站点务必改成这个 timezone: Asia/Shanghai # 时区影响文章时间显示language这一项特别容易被忽略。默认是英文如果不改主题里的一些内置文案比如“”“上一篇”会显示英文中文站点看起来就很别扭。改成zh-CN后支持中文的主题会自动切换文案。timezone也建议显式设置。如果不设生成的时间可能按服务器时区走导致文章发布时间和你实际写的时间对不上尤其是部署到云端自动构建时更明显。3.2 主题选型与安装方式对比Hexo 的主题生态是它的一大优势。选主题我一般看三点更新是否活跃、文档是否完整、移动端适配是否到位。一个长期不更新的主题遇到 Hexo 版本升级很容易出兼容问题。安装主题有两种主流方式。第一种是直接把主题文件下载到themes目录优点是简单直接缺点是主题更新时你得手动替换。第二种是用 Git 子模块的方式引入优点是主题可以独立更新缺点是操作稍复杂对新手不够友好。我个人的建议是新手先用直接下载的方式把博客跑起来、写起来最重要。等你对整套流程熟悉了再考虑用子模块管理主题。安装完主题后在_config.yml里把theme字段改成主题文件夹的名字这一步千万别写错否则主题不生效。3.3 主题配置的通用套路每个主题都有自己的配置文件通常在主题目录下的_config.yml。虽然各主题参数不同但套路是相通的一般包含这几类导航菜单配置顶部导航栏显示哪些页面比如首页、归档、关于。社交链接配置你的各个平台主页地址显示为图标。样式开关是否开启暗色模式、代码高亮风格、动画效果等。第三方集成评论系统、访问统计、搜索功能的开关和密钥。改主题配置时我强烈建议改一项、预览一次。一次性改一大堆再刷新出了问题根本不知道是哪一项引起的。这个习惯能帮你省下大量排查时间。3.4 新建文章与 Front-matter 写法写文章用这条命令hexo new 文章标题它会在source/_posts下生成一个 Markdown 文件开头有一段被三条横线包裹的配置区叫 Front-matter--- title: 文章标题 date: 2024-01-01 10:00:00 tags: - 标签一 - 标签二 categories: - 分类名 ---这里有几个细节值得说。date如果不写Hexo 会用当前时间但如果你在云端自动构建时间可能不准所以重要文章建议手动写死。tags和categories的区别是分类是一对多的层级关系标签是多对多的自由标记。我的习惯是分类少而稳定比如“技术”“生活”标签多而灵活比如具体的技术名词。注意Front-matter 里的冒号后面必须有一个空格这是 YAML 语法要求。漏了空格会导致解析失败文章可能直接不显示。4. 从本地生成到远程仓库的完整部署链路4.1 生成静态文件与本地验证文章写完执行生成命令hexo generate简写是hexo g。这条命令会把source下的 Markdown 和资源渲染成完整的 HTML输出到public目录。生成完成后我建议先本地预览一遍再部署hexo server重点检查三件事文章能不能正常打开、图片能不能正常显示、导航链接有没有失效。这三项没问题基本就可以部署了。很多人跳过本地验证直接推结果线上出问题再回头查效率反而低。4.2 创建远程仓库的命名规则在代码托管平台创建一个新仓库。这里有个极其关键的命名规则如果你打算用平台提供的默认域名访问博客仓库名通常需要遵循特定格式一般是“用户名.github.io”这种形式。如果仓库名不符合规则默认域名就访问不到只能走自定义域名。创建仓库时建议设为公开仓库。虽然私有仓库也能配合某些付费功能实现托管但对个人博客来说公开仓库最简单、最省事而且源码公开本身也不是什么坏事。4.3 部署插件的安装与配置Hexo 本身不直接负责推送需要装一个部署插件npm install hexo-deployer-git --save然后在_config.yml里配置部署信息deploy: type: git repo: 你的仓库地址 branch: 部署分支名这里的branch需要重点说明。如果你用的是“源码和生成结果分开管理”的方案源码放一个分支生成结果放另一个分支比如 main 或 gh-pages那么这里填的就是生成结果所在的分支。具体填哪个取决于你在托管平台里把哪个分支设置为发布源。配置完成后执行三连命令hexo clean hexo generate hexo deployclean是清掉缓存和旧的 public 目录避免残留文件干扰generate重新生成deploy推送到远程。这三步合起来可以简写为hexo clean hexo g hexo d。4.4 自动化部署把三连命令交给平台执行手动执行三连命令虽然简单但每次都要敲一遍时间久了会烦。更优雅的方案是配置自动化你只推送源码平台自动帮你生成并发布。实现思路是这样的在仓库里配置一个自动化流程文件告诉平台“当我推送源码时帮我安装依赖、执行生成命令、把结果发布出去”。这个流程文件通常放在特定目录下用平台约定的语法编写。一个典型的流程包含这几步检出代码、安装 Node 环境、安装依赖、执行生成、发布产物。每一步都有对应的配置项。这里最容易出问题的是依赖安装和权限配置。依赖安装要确保用的是项目锁定的版本权限配置要确保自动化流程有权限把结果推送到发布分支。实操心得自动化流程第一次配置时建议先在一个测试仓库里跑通确认无误再迁移到正式博客仓库。直接在主仓库调试一旦流程写错可能把发布分支搞乱。4.5 自定义域名的绑定要点如果你有自己的域名绑定流程分两步。第一步是在仓库的设置里填写自定义域名平台会生成一个验证记录。第二步是在你的域名解析服务商那里添加一条指向托管平台的记录。这里有个细节域名解析生效需要时间短则几分钟长则几小时。刚配置完访问不了是正常的别急着反复改配置。另外绑定自定义域名后建议开启强制加密访问避免出现部分资源加载失败的问题。5. 常见问题排查与避坑经验实录5.1 部署后页面 404 或样式丢失这是新手遇到最多的问题。排查顺序我总结成一张表现象可能原因排查方法首页 404发布分支设置错误检查仓库设置里的发布源分支是否和部署分支一致页面能开但没样式资源路径配置错误检查配置文件里的根路径设置子目录部署需特殊处理部分文章打不开文件名含特殊字符检查文章文件名避免空格和中文标点图片不显示图片路径写法问题确认图片放在正确目录Markdown 引用路径与实际一致样式丢失这个问题十有八九是根路径配置不对。如果你的博客部署在子路径下比如仓库名作为路径需要在配置里把根路径改成对应的子路径否则所有资源都会去根目录找自然找不到。5.2 自动化流程执行失败的典型原因自动化流程跑失败终端日志是最好的老师。我遇到过的几类典型错误第一类是依赖安装失败通常是 Node 版本和依赖不兼容。解决办法是在流程配置里显式指定 Node 版本和本地保持一致。第二类是权限不足表现为推送产物时被拒绝。这需要在仓库设置里给自动化流程授予写权限不同平台的叫法不同但本质都是“允许自动化流程修改仓库内容”。第三类是缓存导致的诡异问题。有时候本地能生成云端却失败清理缓存后重跑往往就好了。所以我在流程里一般会加上清理缓存的步骤。5.3 文章时间显示不对前面提过时区问题这里再展开说。如果你在配置里设了时区但文章时间还是不对检查两个地方一是 Front-matter 里的date是否手动写死二是自动化流程运行环境的时区。最稳妥的做法是文章时间手动写不依赖系统时间。5.4 主题更新后样式错乱主题更新后样式错乱多半是主题配置文件和你的自定义修改冲突了。我的经验是改主题前先备份主题配置文件。更新主题后把备份的配置和新的默认配置对比把自定义项重新填回去。直接覆盖更新很容易丢掉你之前调好的设置。5.5 我踩过的三个真实坑第一个坑是仓库名写错。我一开始没注意命名规则随便起了个名字结果默认域名死活访问不了折腾半天才发现是仓库名的问题。这个坑的教训是动手前先把平台的命名规则看清楚。第二个坑是部署分支和发布分支搞混。源码推上去了但发布源设置的是另一个分支导致线上一直是旧内容。后来我把两个分支的职责在配置里写清楚再也没混过。第三个坑是图片路径用绝对路径。本地预览正常线上全挂。原因是绝对路径指向了本地文件系统。改成相对路径后问题解决。这个坑让我养成了一个习惯所有资源引用一律用相对路径。6. 长期维护与内容运营的实用建议6.1 备份策略源码才是核心资产静态博客最宝贵的不是生成出来的 HTML而是你的 Markdown 源码和配置。我的做法是源码仓库保持更新每次写完文章就推送一次。这样即使本地电脑出问题云端还有完整备份。生成结果不需要备份因为它随时可以从源码重新生成。6.2 写作流程的固化写久了你会发现效率的关键在于流程固定。我的流程是新建文章、写正文、本地预览、推送、等自动化发布。每一步都有固定命令形成肌肉记忆后从写到发布也就几分钟的事。不要每次都临时想“我该先干嘛”那会消耗大量精力。6.3 图片管理的两种思路图片放哪有两种常见做法。一种是放在文章同级目录下建一个同名文件夹引用时用相对路径好处是文章和图片绑定在一起迁移方便。另一种是统一放在一个资源目录里好处是管理集中。我个人倾向第一种因为文章多了以后按文章归档图片更清晰。6.4 什么时候该考虑换方案Hexo 不是万能的。如果你的文章数量到了几千篇生成速度会明显变慢这时候可以考虑构建更快的生成器。如果你需要复杂的交互功能静态博客的补丁方案会越来越吃力可能需要考虑带后端的方案。但对绝大多数个人博客来说Hexo 的适用范围足够宽不用过早担心这些问题。我在实际使用中最大的体会是工具只是工具真正让博客有价值的是持续写下去这件事本身。Hexo 加自动化部署这套组合最大的意义就是把你从技术细节里解放出来让你能把精力放在内容上。配置一次之后就是纯粹的写作和推送这种顺畅感才是它最值得推荐的地方。