废话不多说直接聊聊我自己的经历。作为一个常年折腾各种工具的开发者GitHub Pages配上Hexo这套组合是我用了好几年、踩了无数坑之后依然觉得最舒服的个人博客方案。和那些动辄要买服务器、配数据库、还得防攻击的动态博客比起来Hexo这种静态站点生成器最大的魅力就是“省心”写完一篇Markdown敲一条命令刷新页面就已经上线了。整个过程干净利落没有任何多余的负担。这篇东西不是照着官方文档念一遍而是把我从装环境到日常写作、再到处理各种诡异报错的完整经验捋一遍。如果你正准备搭一个属于自己的技术博客或者已经在用Hexo但总觉得哪里不对劲这篇文章应该能帮你省下不少时间。GitHub仓库当存储、Hexo当生成引擎、Markdown当写作语言这套流程跑通了之后你会发现记录和分享本身就是一件很顺手的事。1. 为什么是Hexo GitHub Pages方案选型背后的逻辑1.1 静态博客与动态博客的本质区别很多人第一次接触博客脑子里默认就是WordPress那种带后台管理界面的东西。但我个人强烈建议除非你真的需要复杂的会员体系或在线交易功能否则技术博客完全没必要上动态方案。动态博客的每一个页面访问服务器都要去查数据库、执行脚本、渲染模板这套流程意味着你需要一台随时在线的机器需要处理安全补丁还需要定期备份数据库。而静态博客生成的全是纯HTML文件交给任何静态托管服务就能跑速度飞快也几乎没有被攻击的入口。拿我自己的访问量来说一篇技术文章被搜索引擎收录之后每天可能稳定带来几十个访问。这点负载对静态文件来说就是洒洒水我甚至见过有人把整个博客挂在一个免费的CDN后面全球访问速度都比很多动态博客快得多。这就是静态方案最核心的价值把复杂的东西留在本地构建阶段把最简单的东西留给服务器。1.2 Hexo在众多静态生成器中的生态优势静态站点生成器这个赛道其实很拥挤国外有Hugo、Jekyll国内的静态博客方案更是五花八门。我当初选Hexo最看重的是它的Node.js生态。当时的Node生态是所有Javascript工具链中最成熟的那意味着Hexo的所有功能都可以通过npm包扩展。后来我陆续装了Feed生成插件、Sitemap插件、SEO优化插件几乎都是几个命令就搞定根本不用自己造轮子。相比之下Jekyll虽然跟GitHub Pages是原生集成但它的主题系统和插件机制用起来总觉得别扭即使它有能够直接使用的Theme gem因为需要Ruby环境的维护成本也让很多新手望而却步。而Hugo的渲染速度确实快到离谱但它的模板语言对新手来说不算友好想要深度定制界面学习曲线相当陡峭。Hexo正好处在两者中间性能足够日常使用配置通俗易懂主题数量在中文技术圈里也积累得很可观。更关键的是Hexo整个中文文档和社区氛围都很好几乎你遇到的每个问题都已经有人踩过坑且给出了解决方案。1.3 GitHub Pages这个承载平台的独特价值GitHub Pages本质上是GitHub提供的一项静态文件托管服务它专门用来承载个人或项目的展示页面。选择它的理由很实在首先免费对于一个几MB到几十MB的静态博客来说它的配额完全够用其次它跟Git的天然亲和力你只需要把生成好的文件推到远程仓库它会自动完成发布整个链路非常完整。最后它的全球CDN节点分布很广这带来更低的内容访问延迟。当然GitHub Pages也有自己的限制比如不适合作为大文件存储或高速动态内容的对外服务且代码仓库建议不要超过一定体积限制。但对于博客这种以文字和少量图片为主的内容形态这些限制几乎可以忽略。正是这种“本地写好、推送即发布”的工作流让人觉得写作本身就是一件顺畅的事。我现在的习惯是先在本地用Markdown编辑器把文章写好再用Hexo的服务在本地浏览器里预览效果确认没问题之后一条命令推上去整个过程不会超过两分钟。提示如果想在国内获得更稳定的访问体验也可以考虑使用Gitee Pages但它的审核流程相对繁琐且更新频率不如GitHub Pages顺畅。绝大多数情况下GitHub Pages就已经足够了。2. 环境准备与Hexo安装从零开始的正确姿势2.1 Node.js与Git的安装细节Hexo是基于Node.js的命令行工具所以第一件事就是把Node.js环境准备好。我建议直接去Node.js官网下载LTS版本因为LTS版本更稳定也经过充分测试不要为了尝鲜去用Current版本虽然差异通常不大但在Hexo这种依赖众多的小工具链里稳定压倒一切。安装完成之后打开终端输入node -v看到版本号输出就说明这一步没问题。Git的安装相对简单Windows下用安装包一路确认即可macOS可以用Homebrew安装Linux则看发行版用各自的包管理器。需要注意的一点是Git装好之后最好顺手配一下全局的用户名和邮箱因为Hexo的部署插件本质上是在调用Git去推代码没有这些信息会导致提交被拒绝。命令行配置方式如下git config --global user.name 你的用户名 git config --global user.email 你的邮箱这套配置不仅对后续Hexo部署有用对日常使用Git的各类操作同样至关重要。我见过不少刚接触Git的新手一开始觉得“这步无所谓”结果第一次执行部署命令时被一连串报错折腾得焦头烂额最后发现原因就是用户名和邮箱没配置。2.2 安装Hexo命令行工具Node.js装好之后安装Hexo本身只需要一条npm命令npm install -g hexo-cli这里有个细节值得展开说明一下。-g参数代表全局安装意味着你不用进入某个特定目录就能直接使用hexo命令。我把Hexo安装在系统级的全局目录里完全是因为Hexo的脚手架工具需要在任意路径下直接调用这与其他通过npx管理的工具链不同用起来更顺手。国内用户如果在执行这条命令时发现下载速度慢到无法忍受可以考虑把npm的镜像源切换到国内源具体操作如下npm config set registry https://registry.npmmirror.com切换完镜像之后下载速度会有肉眼可见的提升。装好之后输入hexo -v如果能打印出版本信息恭喜你Hexo的命令行环境已经就绪。2.3 初始化博客站点的完整流程接下来是创建博客目录的步骤。选择一个你觉得顺手的路径比如我的博客就放在开发目录下的blog文件夹里。然后执行hexo init blog cd blog npm installhexo init会从GitHub上拉取Hexo的官方示例项目这个项目自带了一套默认主题以及完整的基础配置。接下来的npm install会安装项目运行所依赖的所有npm包这个过程通常需要等一会儿。安装完成之后依然在这个目录下执行hexo server浏览器访问http://localhost:4000看到默认的Hexo页面就说明本地环境已经完全跑通了。到这里Hexo博客的骨架就已经立起来接下来要做的就是往里填充自己的配置和内容。注意hexo init执行时需要确保网络连接正常因为它要从远程仓库拉取模板项目。如果一直超时可以多试几次或者检查一下你的网络代理设置是否影响到了git的访问。3. 核心配置深度解析让博客开始有自己的样子3.1 站点主配置文件 _config.yml 的关键项博客建好之后最重要的文件就是根目录下的_config.yml它相当于整个博客的总控制台。打开它你会看到一堆键值对其中大部分都需要根据自己的情况修改。最基础的是站点信息部分包括标题、副标题、作者名、以及用于SEO的语言设置。我以我自己常用的配置为例title: 代码之外的思考 subtitle: 记录技术成长与生活感悟 author: 某开发者 language: zh-CN timezone: Asia/Shanghai别小看timezone这个字段如果你不设置它博客的文章时间会默认使用服务器的UTC时区导致发布时间和实际时间差出8个小时。我当初就因为这个字段没设置所有文章的时间在发布后看都“超前”了整整一个白天排查了好久才找到原因。另外language字段建议明确写为zh-CN这样才能让主题正确加载中文语言包否则菜单和按钮显示的全是英文。站点URL也是必须修改的配置项之一它直接关系到站点地图和SEO的效果。如果你的博客准备绑定自己的域名就填最终域名否则就填https://你的用户名.github.io。这个地址写错了后面生成的站点地图和搜索引擎收录都会出问题。3.2 主题选型与替换流程Hexo默认的主题是我个人认为设计上相对简洁的。但每个人的审美不同因为默认主题的功能性和可定制性都比较基础很多人都会选择替换成第三方主题。Hexo生态里比较知名的主题包括NexT、Butterfly、Cactus等它们各有特色。以我选型的经验我会先在GitHub上搜索候选主题考察它们是否持续维护、文档是否齐全、以及是否支持我需要的功能模块。以我目前正在使用的主题为例替换过程非常标准先进入themes目录克隆一份最新代码然后回到根目录的_config.yml中把theme:后面的值改成主题目录名并删除主题自带的默认配置文件或按文档将其重命名最后清理生成缓存并重新生成即可cd themes git clone https://github.com/某个主题地址.git 主题名 cd .. npm install hexo-renderer-scss --save hexo clean hexo generate这里有个新手常踩的坑很多主题需要额外的渲染器插件才能正常显示样式最常见的缺失是SCSS或Stylus渲染器。如果你换主题后页面变得乱七八糟、没有任何样式多半就是忘了安装对应的渲染插件。不同主题对Hexo版本也有一定的要求安装前注意看主题文档。3.3 主题配置文件的个性化调整主题目录里也有一个_config.yml注意不要和根目录的站点配置文件搞混。根目录的配置管整站逻辑主题目录里的配置管外观和功能模块。拿我用的这个主题举例我在它的配置文件里做了这些调整开启侧边栏社交链接和头像、打开文章阅读量统计、配置了评论系统的接入、把页脚的版权信息和备案信息改成了自己的内容。其中评论系统这一块想多说一句。早期的Hexo博客几乎都在用第三方评论服务有的服务后来因为种种原因关闭了导致无数历史文章失去了评论功能也有的服务接入了太多广告。我自己最终选择了基于GitHub仓库的评论方案把Issues当作评论区来用数据完全掌握在自己手里加载速度也很快。这种方案对Hexo来说虽然不是开箱即用但主题文档里一般都会给出详细的配置步骤。经验之谈主题的配置文件往往是改动频率最高的文件。每次改动之后习惯性地执行hexo clean hexo generate不要偷懒只执行hexo generate。有时候主题的静态资源会有缓存残留不清理干净就会出现样式错乱或功能不生效的奇怪问题。4. 内容创作与发布把写作流程建立成习惯4.1 从Markdown到固定页面每篇文章的诞生之路Hexo的文章源文件是纯Markdown格式存放在source/_posts目录下。创建一篇新文章有两种方式第一种是直接在该目录下新建一个.md文件第二种是用Hexo提供的脚手架命令我通常使用后者因为它会自动生成Front-matter信息hexo new post 文章标题执行完这条命令Hexo会在source/_posts目录下根据标题创建一个Markdown文件并在文件顶部自动生成一段Front-matter内容大致长这样--- title: Github个人博客创建Hexo date: 2025-01-15 10:30:00 tags: categories: ---这段用三个短横线包围的区域就是Front-matter它是Hexo解析文章元信息的关键依据。title会覆盖文件名成为文章的标题date决定文章的发布时间并影响排序tags和categories则是给文章打上的分类标签。我习惯的写法是给每篇文章至少填一个分类和两三个标签这样后续在博客页面上按标签索引会方便得多对SEO也更友好。4.2 本地预览与图片处理技巧写作过程中最常用的命令是hexo server它会在本地4000端口起一个预览服务支持文件变更自动刷新。我通常在写作时开着这个服务每写完一个段落切到浏览器扫一眼效果比全部写完再统一查看要高效得多。关于文章里的图片这里值得专门说。图片处理是很多新手会卡住的地方因为图片一大博客的体积就会失控也会拖慢页面加载速度。我目前的方案是对于截图类图片用工具压缩到合理的体积再放进source/images目录下对应的文章文件夹里引用路径也简短地使用相对路径方式。对于比较大的图片或涉及隐私的附件我用对象存储服务来托管文章里直接贴外链。这套混合方案兼顾了速度和可维护性。做本地存储时注意GitHub仓库的体积要控制在合理范围内我建议仓库整体大小不要过大否则每次操作都会变得迟钝。4.3 部署命令与整个发布链路的手感当文章在本地预览确认无误后发布到GitHub Pages只需要两条命令hexo clean hexo deployhexo clean的作用是把之前生成的public目录删掉这个存放最终静态文件的目录每次生成都会重建如果不清空容易出现旧文件残留。hexo deploy这个命令会执行两件事先用当前的Markdown源文件重新生成完整的静态页面再调用部署插件把生成结果推送到远程仓库。整个过程的逻辑链条是文章源文件在本地构建构建产物推送到远程仓库仓库的变化触发GitHub Pages的自动发布。部署完成之后等上几十秒让GitHub Pages完成刷新访问https://你的用户名.github.io就能看到新文章。我刚开始用这套流程的时候总是忍不住反复刷新页面后来才摸清它需要一点构建时间。习惯了这种节奏之后整个发布过程给人的感觉就是非常干净利落。5. 日常维护与搜索优化让博客持续健康生长5.1 代码高亮配置与阅读体验优化技术博客和普通生活日志最大的区别就是代码展示的频率极高。代码块的可读性直接决定文章的专业观感。Hexo本身内置了代码高亮功能但在主题层面通常还有更细致的微调空间。以我目前的主题为例它在配置文件里提供了高亮主题的选择和是否显示行号、复制按钮等选项。我个人的建议是行号一定要开因为当你需要引用代码中的某一行时有行号会方便很多复制按钮一定要有读者一旦在文章里看到大段代码复制是一种刚需主题如果没这个功能可以考虑通过代码注入来实现。如果想要更高阶的代码交互效果部分主题会集成对应的代码渲染插件但这也是整个页面体积膨胀的来源所以我特意关闭了那些会影响性能的开销较大的功能选项。5.2 让搜索引擎更容易找到你博客建好之后如果完全不做任何SEO工作搜索引擎的收录会比较缓慢甚至一直不收录。Hexo生态里解决这个问题的思路很明确装几个插件生成必要的SEO基础设施。需要安装的插件通常包括用于文章推送的通用插件以及用于生成站点地图的插件。在根目录执行安装npm install hexo-generator-sitemap --save npm install hexo-generator-feed --save装好之后在根目录的_config.yml里配置好对应的插件参数再执行一次hexo clean hexo generate就会发现public目录下多了sitemap.xml和feed.xml这类文件。前者是给搜索引擎看的站点地图后者是生成RSS订阅源的关键对于希望聚合订阅的老用户来说RSS是需要在博客显眼位置被明确呈现的。有了这些基础之后再考虑做主动提交把站点地图提交到搜索引擎的站长平台。这里有个值得重视的经验点搜索引擎爬虫对新站尤其谨慎刚开始那段时间文章的收录可能会比较缓慢尤其对个人小站的抓取频率可能相对克制。不用急躁持续更新有价值的内容收录量自然会慢慢涨起来。5.3 数据备份与长期稳定的保障GitHub仓库本身已经提供了完整的版本管理能力这意味着博客的所有源文件都在Git的掌控之下。我现在的习惯是每次写完文章都会及时commit并push到远程仓库这样无论是本机硬盘损坏还是误删文件都能随时从远程恢复。但这里依然有一个隐患如果远程仓库所在的账号或组织出现问题就有可能导致失去对整个仓库的访问。文章和图片源文件本身并没有第二份冗余。我的解决方式是每个月手动把整个博客目录打包上传到对象存储服务或者备份至另一处云端存储。虽然这种备份频率不算高但足够应对绝大多数意外情况了。我从实际经历中得到的教训是写博客最怕的不是写得不好而是辛苦写的几十篇文章因为一次磁盘损坏全部归零。自从经历过一次数据丢失之后备份就成了我每次重大更新之后必须执行的动作。6. 常见问题与排查技巧实录6.1 部署失败Deploy命令报错的常见原因与对策部署命令执行失败可能是新手会遇到的最常见问题。通常错误信息里会提示“远程仓库拒绝访问”或“权限不足”之类的字眼。根据我踩过坑的经历原因不外乎以下几种一是Git的认证信息太旧或配置错误二是远程仓库地址配错三是仓库本身不存在。解决思路依次是这样的先检查根目录配置里的部署地址确认仓库是否真实存在且拼写无误接着确认本地Git是否已经完成认证最简单的验证方式是执行git ls-remote 仓库地址如果能正确列出远程引用就说明认证没问题。如果是令牌过期去GitHub设置页面重新生成一个新的访问令牌来替换旧的。还有一种情况是本地配置了代理导致Git连接失败遇到这种情况可以先临时关闭代理再测试。6.2 生成异常clean之后页面反而打不开怎么办hexo clean之后紧接着执行hexo generate理论上这个步骤能让一切从头再来起到的效果也很显著但偶尔会遇到生成出来的页面是一片空白的情况。排查第一步是看终端输出有没有报错信息比如某个文件引用了不存在的变量或者模板语法有误。第二步是检查主题目录和配置文件之间是否有不匹配有些旧主题的配置字段在新的Hexo版本里已经废弃会导致部分功能失效。如果排查一圈依然无果还有个终极大招直接删除node_modules目录和package-lock.json文件然后重新执行npm install。依赖树一旦出现深层的兼容性问题与其花几个小时手动定位不如让包管理器重新解析一遍。这种“核弹级”的重装方案我用了至少三次每次都成功解决了疑难杂症。6.3 图片显示异常本地能看线上却裂开的真相本地预览一切正常部署上线后文章里的图片全部变成裂图这是绝对高频的问题。本质原因在于引用路径写死了本地地址或用了不兼容的相对路径。Hexo在生成文章时对图片的路径处理有自己的一套规则如果Markdown里的图片引用方式是网络绝对路径就没什么问题如果是本地相对路径就要确保它始终相对于source目录来解释。我建议的稳妥做法是放弃直接在Markdown里用相对路径引用/images/xxx.png这种方式在处理草稿、归档时容易出问题。更可靠的方式是在文章Front-matter中启用资源文件夹特性把图片和文章放在同一个目录下引用时直接用文件名就可以。虽然官方文档对这种不同方式的路径解析逻辑有详细说明但很多人都会在这里卡住所以我直接推荐最不容易出错的那种方式。6.4 访问速度慢可感知的优化手段GitHub Pages在国内的访问速度有时表现得不尽如人意这受制于网络出口的物理距离和拥堵程度。在不动服务器的情况下能做的优化其实很直接压缩图片是第一优先级一张几兆的截图直接按比例压缩到之前体积的几分之一页面打开速度会快非常多其次是减少不必要的JavaScript和CSS依赖某些主题默认会加载一堆用不到的库可以在配置里关掉。另外还可以用免费CDN服务来分发你存放在公共存储空间的静态资源让样式表、脚本和图片这些体积占比较大的资源通过经过优化的节点加载而HTML主文档继续走GitHub Pages。这种双管齐下的策略是我实测下来效果最明显、成本也几乎为零的方案。7. 长期使用的几点体会从第一次成功把文章部署上线到现在每天稳定记录和输出Hexo GitHub Pages这套方案陪伴了我很长时间。它最让我欣赏的一点是它把技术博客的门槛降到了几乎为零不需要买服务器不需要折腾数据库不需要担心被攻击更不需要为维护一套后台管理系统操心。你唯一需要认真对待的就是写作本身。如果你正准备开始搭自己的博客我的建议是先别急着折腾那些花哨的主题特效和插件把最基本的环境跑通、把第一篇文章发出去完成这个从零到一的闭环比什么都重要。很多新人在第一步就卡了很久忙了一晚上连第一条文章都没成功上线热情很容易在初期被耗尽。先把最朴素、最简单的版本跑起来哪怕只有一个标题和一段话那份“我的东西上线了”的成就感会推着你继续往前走。我个人这几年踩坑踩出来的最深体会就是在这些看似琐碎的步骤上多一点耐心和细心。配置好用户名邮箱、写好站点URL、确认时区正确、部署前先clean这些小细节单看都不起眼但它们共同构成了一个顺畅的写作体验。当你习惯了在这种顺畅的节奏里记录思考时维护博客就不再是一种负担而是你自己给自己搭建的一方安静而稳定的自留地。