写博客这事儿折腾过WordPress、也用过一段时间动态站最后我的个人博客一直固定跑在Hexo上。原因很简单Markdown写作、Git管理、纯静态文件托管不用养服务器也不用担心数据库被挂发布一次到GitHub Pages之后全世界都能用固定链接访问。这个过程里踩过的坑不少从Node版本不兼容到主题配置失效再到图片路径神秘消失都遇到过。这篇教程打算把完整流程重新捋一遍无论是刚接触Hexo的新人还是想重新搭建一次的旧用户都能照着手动搭起来并顺手解决几个高频翻车点。1. 内容整体设计与思路拆解1.1 为什么选择Hexo而不是其他博客框架先聊一下选择的问题。静态博客生成器里常见的就是Hexo、Hugo、Jekyll这几类。Jekyll和GitHub Pages原生结合最紧密但Ruby环境在Windows上配置起来比较折磨人主题也大多偏向极简英文风。Hugo生成速度很快Go语言单二进制文件但它的模板语法和内容组织方式学习曲线比Hexo陡。Hexo的优势在于Node.js生态成熟安装只需要npm一条命令主题和插件数量在几个框架里最多中文社区活跃出问题搜一下基本都有现成答案。而且Hexo对写作者非常友好一篇新文章就是Markdown文件加几行Front Matter写完直接hexo g hexo d就把整个站点生成并推送上线。不用碰Apache配置、不用处理PHP版本、不用想着备份数据库。整个博客本质就是一组静态文件随便扔到任意Web服务都能跑这是它的核心价值。1.2 静态博客的整体工作流Hexo的工作流程可以简化为本地写Markdown文件 → Hexo生成静态页面 → 推送到托管平台。中间的细节是每篇文章由Front Matter标题、日期、标签、分类和正文组成Hexo会把这些信息渲染成HTML页面同时生成归档页、标签页、首页的分页列表。因为输出是纯静态页面访问速度快不依赖后端逻辑所以不存在被攻击注入的问题也不怕高流量把服务器打挂。整个发布链路里最核心的两个命令就是hexo ggenerate生成和hexo ddeploy部署。很多初期用户会混淆这两个命令实际上先执行hexo g再执行hexo d就对了。如果修改了配置或主题文件还需要先hexo clean清掉缓存再重新生成否则经常碰到改动不生效的怪问题。这套流程我用了几年稳定得离谱除了偶尔换主题重新生成以外基本没出过岔子。1.3 部署目标选型GitHub Pages为主其他方案为辅Hexo生成出来的静态文件可以部署到很多地方GitHub Pages、Gitee Pages、Netlify、Vercel甚至一个简单的Nginx服务器都行。这里优先讲GitHub Pages因为它是GitHub官方免费提供的托管服务仓库地址就是站点地址配合Git操作链非常顺滑也不用交任何费用。要注意的是GitHub Pages分为两种个人/组织站点和项目站点。个人站点仓库名必须叫用户名.github.io构建出的站点地址就是https://用户名.github.io。项目站点则可以是任意仓库地址变成https://用户名.github.io/仓库名/。对个人博客来说直接创建用户名.github.io这种仓库最省事不用额外处理子路径问题。2. 核心细节解析与实操要点2.1 环境准备Node.js的版本选择Hexo是Node.js生态里的工具所以第一步永远是装Node.js。版本选择上我建议装LTS版长期支持版不要追求最新尝鲜版。Node的版本对Hexo的影响很直接如果版本太高或太低都可能出现node-sass这类原生模块编译失败的情况报错日志里常看到Failed at the node-sass版本号 postinstall script。避免这个问题最省心的方式就是使用LTS版并保持npm源正常然后安装Hexo CLI。检查环境是否就绪只需要两个命令node -v npm -v能看到版本号就说明Node和npm装好了。如果提示找不到命令一般就是路径没加入环境变量Windows用户重新安装时记得勾选“Add to PATH”。2.2 安装Hexo与博客目录初始化环境没问题之后用npm全局安装Hexo命令行工具npm install hexo-cli -g接着在一个干净的目录里初始化博客hexo init blog cd blog npm installhexo init会自动拉取一套Hexo默认模板站点包括基础目录结构、config文件和landscape主题。npm install则是根据模板里的依赖清单安装所有需要用到的模块。这个初始化过程完成后直接运行hexo s浏览器访问http://localhost:4000就能看到默认站点。这里有一个实际操作中的心得hexo init成功后建议先进_config.yml把站点标题等基础信息改了再继续折腾主题不然每次刷新页面都看到Hello World心态上总觉得没搭好其实只是默认内容而已。2.3 目录结构理解初始化生成的目录结构是Hexo约定好的必须理解每个文件夹的用途才能高效使用。核心的几个如下source/存放所有文章源文件.md后缀的文件就是博客文章_posts目录下的Markdown文件会被渲染为文章页面。另外source里还可以放about、tags、categories等自定义页面文件这些会原样生成到站点根目录。themes/存放主题每个主题是一个独立文件夹里面有layout模板文件夹、source静态资源文件夹和_config.yml主题配置文件。scaffolds/脚手架模板执行hexo new时用来生成文章模板可以自己改动模板内容。_config.yml站点级配置文件站点标题、URL、语言、主题名称、部署配置全在这里。记住一个原则写文章只动source/_posts换样式改themes全局设置才动根目录的_config.yml。刚上手的人最容易把三个东西混在一起改错配置哪都出问题但说不清为什么。3. 实操过程与核心环节实现3.1 站点基础配置修改进到博客根目录打开_config.yml。这个文件是整个Hexo的起点先改这几个关键字段title: 你的站点名 subtitle: 副标题 description: 站点描述 author: 作者名 language: zh-CN timezone: Asia/Shanghai其中language很关键改成zh-CN后插件和主题的界面语言会变成中文。url字段初次配置时可以先用https://你的用户名.github.io占位等部署完GitHub Pages以后再改过来因为这个字段是生成sitemap和canonical链接的基础。改了_config.yml之后用hexo clean hexo g重新生成再hexo s预览确认标题等信息生效。这里要记住清理缓存因为很多故障都是旧缓存导致的页面不更新。3.2 安装一款好用的主题默认主题landscape比较基础一般都会换掉。主题选择上初学者推荐Next主题或Butterfly主题。Next主打极简双栏配置项精简文档清晰Butterfly功能更丰富支持背景图、卡片样式、代码高亮等颜值高但配置也更多。我个人偏向Next因为稳定性和视觉效果在中长期使用中很舒服。以Next为例安装方式直接git clone https://github.com/theme-next/hexo-theme-next.git themes/next然后在根目录_config.yml把theme字段改为next。很多主题还支持通过npm安装那就要按主题文档来操作不要混用。换完主题之后注意主题也有一个_config.yml位置在themes/next/_config.yml。这个是主题的配置入口菜单显示哪几项、侧栏展示什么、开启哪些功能都在这里调。但记住一个坑根目录_config.yml和主题目录_config.yml是两个不同的文件位置别搞混。根目录管全局主题目录管外观样式改到哪里都会多少出问题。3.3 写文章与Front Matter格式写作流程很简单执行hexo new 文章标题这会按scaffolds/post.md里的模板在当前时间创建一个新Markdown文件路径类似source/_posts/2024-01-01-文章标题.md。这个文件开头有一段Front Matter--- title: 文章标题 date: 2024-01-01 12:00:00 tags: - 标签1 - 标签2 categories: 分类 ---这些字段会被用来生成文章页、归档页和分类页。title会作为页面标题tags和categories是组织内容的维度。一些主题还支持cover、description等自定义字段这些能提升文章在博客首页的展示效果。写作正文部分就是纯Markdown正常写二级标题、正文段落、代码块就行了。注意Front Matter的冒号后面必须有空格不然yaml解析会出错生成时报empty value之类的错。很多新人卡在这一步报错原因是解析器不认识那个字段。3.4 图片与静态资源处理图片处理是Hexo使用里非常容易踩坑的环节。有两种常见处理方式。第一种是配合post_asset_folder开关使用。在根目录_config.yml里设置post_asset_folder: true这样每次新建文章时source/_posts会同步创建一个同名的图片文件夹把图片放进这个文件夹然后在文章里用相对路径引用。这适合单篇文章配图很多、需要集中管理的场景。第二种是新建source/images文件夹把全站共享的图放进去文章里用/images/xxx.jpg引用。这种方式适合logo、头像、站点背景图这类全局资源。两个方案都不复杂关键是要想清楚哪类图片走哪个路径。有个从实践中来经验尽量少用图床因为图床的图片外链随时可能失效而你的博客是要长期存在的。图片放本地文件夹里哪怕空间大点也踏实Git维护也方便。3.5 部署到GitHub Pages部署是Hexo使用里另一道门槛但也只是几步。先在GitHub上创建一个新仓库仓库名必须是你的GitHub用户名.github.io。创建时不要勾选添加README保持空仓库这样待会儿推送时不容易产生冲突。然后在博客根目录_config.yml最下面找到deploy配置段deploy: type: git repo: https://github.com/你的用户名/你的用户名.github.io.git branch: main注意type默认是git而不是GitHub。接着安装部署插件npm install hexo-deployer-git --save之后每次发布执行hexo clean hexo g hexo dhexo d会自动把站点生成目录public/对这个插件来说实际是临时目录里的内容推送到你配置的仓库分支。推完之后浏览器访问https://你的用户名.github.io就能看到你的博客了。首次推送后几分钟内页面可能显示404这是正常的等GitHub构建好就会恢复。3.6 自定义域名与HTTPS配置如果你的博客想用自己的域名而不是用户名.github.io在部署配置之外还需要做两件事第一在仓库设置里的Pages页面填上你的自定义域名第二在DNS服务商那边添加一条CNAME或A记录。建议直接在本地source目录建一个名为CNAME的文件内容就写一行你的域名比如blog.example.com。这样做的好处是每次hexo d推送后文件都会跟着进仓库GitHub Pages不会因为生成过程丢失自定义域名配置。域名解析记录添加完就能通过个人域名访问博客GitHub会自动签发HTTPS证书这个不用额外配置稍等生效就行。3.7 多语言站点配置多语言这个功能如果一开始没规划好后面改起来比较费劲。但规划好其实也不难。Hexo的多语言方案大致有两种。第一种是使用官方多语言插件hexo-generator-i18n。这个插件支持生成多语言首页和文章副本。安装之后需要在_config.yml里配置支持的语种和默认语言language: - zh-CN - en i18n: generator: posts: false pages: false使用这个插件时文章的Front Matter里写上lang: zh-CN或lang: en插件会按语言归类文章。这种方式的优点是结构清晰用/en路径访问英文内容/访问中文内容。缺点是需要为同一篇文章写多个语言版本内容维护成本高。第二种是NexT主题自带的多语言界面。这类主题本身支持界面文字按语言切换_config.yml里的language设为zh-CN时菜单、按钮、分页这些界面元素全变中文。这种方式的“多语言”侧重于界面语言而不是内容语言。如果你只是想让主题界面显示中文直接把language改成zh-CN就行并不需要额外的插件。如果要做真正的双语博客我建议用插件方案因为内容和界面分开管理结构更干净。英文环境hexo s -l en和中文环境各看各的文章不会互相干扰。踩过的小坑是插件版本和主题兼容的问题务必先读插件文档确认用法再动手改配置。4. 常见问题与排查技巧实录下面这些问题都是实操中反复遇到的典型故障整理成速查表直接对照解决就行。现象原因解决方式hexo s无输出且端口被占4000端口被其他进程占用运行hexo s -p 4001自定义端口修改配置后页面无变化旧缓存未清理hexo clean后重新hexo ghexo d报错无法连接仓库地址或分支写错检查_config.yml的repo与branch配置新文章时间显示1970Front Matter缺date字段或yml格式有误补上date字段并检查冒号后面加空格图片引用404引用路径与文件实际位置不符确认post_asset_folder开关状态并使用对应路径文章中文乱码文件编码格式非UTF-8用UTF-8编码重新保存文件部署成功但访问404GitHub Pages还没构建完或仓库名不对等一两分钟刷新检查仓库名是否为用户名.github.io自定义菜单无法显示主题配置里菜单项未开启在主题_config.yml里打开对应菜单项4.1 Windows环境下端口冲突与权限问题Windows系统跑Hexo最常见的是端口冲突和权限问题。有一次我执行hexo s终端提示EADDRINUSE一看就知道4000端口被占了。解决办法很简单用hexo s -p 8000换个端口就行。这不算什么大事但如果每次都遇上也怪烦的查一下是什么程序占用端口并关掉更好。另一个Windows特有的问题是PowerShell执行策略限制脚本执行。如果安装依赖或执行命令时报权限错误试试用管理员身份运行终端或者把执行策略调整为RemoteSigned。4.2 部署GitHub Pages时的三类坑第一类坑是仓库名字不对。GitHub Pages个人站点要求仓库名严格等于用户名.github.io如果建错了名字页面永远不会出现在预期地址上。第二类坑是分支名不一致。新仓库默认分支可能是master也可能是mainGitHub现在默认用main。_config.yml里的branch字段必须与实际分支一致推错了地方部署自然失败。第三类坑是Git凭据问题。部署推送时需要登录GitHub账号如果本机Git配置过其他账号可能推送时报权限不足。可以用git config --list查看当前账号必要时单独配置本项目内的用户名和邮箱。4.3 主题和插件兼容性问题主题和插件的兼容是很多疑难问题的根源。比如某些主题基于NexT的旧版本开发但插件升级到新版本后接口变了主题渲染就异常。这种情况没有万能解但有一个排查思路锁定版本。在package.json里把已知能用的插件版本固定住不要轻易升级。Hexo本身也一样版本大版本升级时要先看官方升级日志再决定要不要跳版本。另一个心得是不要同时装一大堆功能相似的主题和插件。主题只能启用一个插件装得过多反而拖慢生成速度还可能互相冲突。能用主题自带的功能解决的就不要额外装插件保持依赖清单越干净博客寿命越长。4.4 备份与迁移博客写多了以后最担心的就是本地电脑出问题导致文章丢失。Hexo的文章是本地文件这种风险是客观存在的解决方式就是保持整个博客目录纳入Git管理。在hexo init后马上执行git init git add . git commit -m initial之后每次写完文章提交一次把仓库推到GitHub的另一个私有仓库里别和Pages仓库混淆。这样换电脑时只需要克隆仓库、npm install、npm install hexo-cli -g整套环境就恢复了。这个操作属于一次性投入长期受益强烈建议第一时间做。5. 实战演练从零搭建一个完整博客上面分步讲了很多但要形成一个整体流程最好还是跟着完整跑一遍。下面用一个实际场景把全部环节串起来从新电脑开始到最后发布上线并配置多语言。5.1 全流程命令实录在一台装好Node的机器上依次执行下面这些命令就能跑通全流程# 安装Hexo CLI npm install hexo-cli -g # 初始化博客 hexo init myblog cd myblog # 安装依赖 npm install # 本地预览 hexo s预览确认无误后修改基础配置# 打开_config.yml修改title、author、language、url等安装主题git clone https://github.com/theme-next/hexo-theme-next.git themes/next修改根目录_config.yml中theme: next同时设置language: zh-CN。创建第一篇文章hexo new 我的第一篇博客编辑文章Markdown文件写点内容然后生成并预览hexo clean hexo g hexo s本地确认无问题去GitHub创建用户名.github.io仓库配置部署字段deploy: type: git repo: https://github.com/用户名/用户名.github.io.git branch: main安装部署插件并发布npm install hexo-deployer-git --save hexo clean hexo g hexo d等上几分钟访问https://用户名.github.io博客就正式上线了。5.2 多语言配置实战想在这里加一个英文版本入口就按这个方式做。先安装多语言插件npm install hexo-generator-i18n --save再修改_config.ymllanguage: - zh-CN - en i18n: generator: posts: false pages: false写文章时在Front Matter里加lang: en标记英文文章--- title: Hello Hexo lang: en ---中文文章就保留lang: zh-CN。访问/en路径就能看到英文内容的独立站点配置。再为中文文章建分类和标签页每个页面也要考虑语言版本不过这一步可以根据博客的规划慢慢加。5.3 上线后的日常维护任务清单上线不等于完事博客日常保养也是要做的。我列一份操作清单照着做就行每次升级Node或Hexo前先把博客整个备份提交到Git仓库。定期检查hexo g生成过程有无警告信息有就顺手修掉。每发布几篇文章后用hexo sitemap生成站点地图方便搜索引擎收录。域名如果换了记得同时更新DNS和_config.yml里的url字段保持链接一致性。保持订阅功能开启很多主题自带RSS生成配好Feed插件后读者才能方便订阅。主题和插件安装前看GitHub仓库的星标、更新日期别选长期不维护的来用。实际用下来Hexo真的是那种“折腾一次受用很久”的工具。初始搭建那几天可能会遇到各种小问题但配置一旦稳定后面写文章就完全专注在内容上了再也不用关心服务器状态、数据库连接这类事情。我个人体会最深的一点是不要把博客搭建这件事变成一个无休止的主题美化工程先能把文章发出去再逐步优化结构和样式这样节奏舒服效果也更好。