1. 为什么我最终选择了Hexo加GitHub先说结论个人博客这事儿最难的一步不是写作而是“让自己写的东西稳定地挂在网上”。我折腾过虚拟主机、云服务器也试过几款动态博客程序绕了一大圈之后近几年一直稳定使用的组合就是Hexo加GitHub Pages。Hexo是一个基于Node.js的静态博客生成器你只管用Markdown写文章它会把所有内容转换成一套纯静态的HTML网页GitHub负责托管代码并且免费提供Pages站点服务。两者拼在一起等于你拥有了一个理论上一分钱托管费都不用花的个人博客。这套方案很适合三类人第一类是喜欢用Markdown写东西、对花哨后台无感的文字型用户第二类是刚接触前端或命令行、想借搭博客学点Git和部署知识的入门开发者第三类是只想要个干净稳定、不想被各种插件和数据库拖累的长期写作者。它解决的痛点是动态博客容易出现数据库崩溃、插件冲突、服务器被攻击的问题而静态博客把这些全绕开了——没有数据库没有服务端脚本只是一堆文件被扔到网上自然稳定得很。我最早也犹豫过毕竟现在写作平台那么多为什么还要自己搭但自己搭博客的最大价值是“域名、内容、数据都在自己手里”不受平台规则约束还能按照自己的审美完全定制页面。这篇文章会把从零到一、从本地写到线上部署的完整细节都摊开讲按我实际动手的顺序来每个环节都会解释为什么要这么做以及我踩过哪些坑。2. 拆解Hexo博客的整体工作流程在敲任何命令之前有必要把这套博客系统的运行机制理清楚。很多新手失败往往不是因为操作难而是没搞明白“哪条命令在干什么、文件改完去了哪里”。2.1 Hexo和GitHub分别扮演什么角色Hexo是“生成器”它的输入是你在source目录下写的Markdown文章输出是public目录里一堆后缀为.html、.css、.js的静态文件。生成过程内置了一个渲染引擎会把你写的Markdown转换成网页同时套用主题模板把导航、归档、标签这些页面结构拼装出来。GitHub在这个体系里承担两个身份一是代码仓库保存你的Hexo工程源文件二是Pages站点服务器存放Hexo生成出来的public目录内容并在你提交后自动对外提供访问。理解这个分工至关重要。我见过有人直接把整个工程目录提交上去结果打开站点一片空白原因就是Pages没有拿到最终生成的网页文件而是拿到了一堆等待渲染的Markdown源码。可以这么记Hexo生成的是商品GitHub Pages是货架git push是上货动作三者缺一不可。2.2 三条目录必须分清楚整个项目里你会频繁接触到三个顶层位置忽略任何一个都可能出事。工程根目录也就是hexo init之后生成的Blog文件夹。它里面包含_config.yml、source、themes、public等。这里所有文件都属于“原料”或“工具”。source目录专门放Markdown文章和图片素材。你在写作时写的所有.md文件都在这里主题里的关于、标签、分类页面也在这里定义。public目录由Hexo根据source内容生成。这个目录里的文件可以直接放到任何静态服务器上运行。部署时推送到GitHub Pages的正是这个目录的内容而不是整个工程。2.3 hexo命令与git命令的分工一开始很容易把两套命令混在一起。我建议记住一个简单分工hexo命令管“生成”git命令管“上传”和“版本管理”。每次写完文章在根目录执行hexo g把文章渲染成网页再执行hexo s就能在本地浏览器预览效果。确认没问题了执行hexo d它会自动调用git把public目录推送到GitHub Pages仓库。要注意hexo d推送的只是public目录工程源码本身的保存和备份是你自己的事。我通常会把整个工程目录单独推到一个私有仓库与Pages用的公开仓库分离这样换电脑时clone下来就能继续写不用重新配置主题和依赖。3. 搭建前的环境准备与基础配置3.1 需要安装的三样东西正式开始前我建议把环境一次配齐中途断在装依赖是最消磨耐心的。Node.js是前提Hexo就是跑在它上面的。安装时尽量选LTS长期支持版版本太新偶尔会有插件不兼容的问题。装完后在终端执行node -v和npm -v确认输出版本号再继续。Git用于版本管理和部署推送。安装时如果不太清楚选项一路默认即可。装完执行git --version确认。Windows用户注意安装过程中选择“从命令行使用Git”这能保证后面hexo d调用git时不会找不到环境变量。GitHub账号用于创建仓库和开启Pages服务。注册好后建议顺手配置SSH密钥配置完成后执行ssh -T gitgithub.com看到提示成功的信息就说明本机和GitHub之间的通道已经打通。后面部署时用SSH方式比起HTTPS方式更省事不用每次输密码。3.2 初始化一个Hexo站点环境就绪之后开始初始化。找一个你想要放置博客的文件夹执行npm install hexo-cli -g全局安装Hexo命令行工具。接着执行hexo init blog它会自动拉取一个基础站点模板并安装核心依赖。这个命令会做三件事创建目录结构、下载默认主题、安装node_modules依赖包。整个过程中如果有网络波动导致警告别忽视稍后执行npm install再补装一次。初始化完成后进入blog目录执行hexo s然后打开浏览器访问localhost:4000或hexo s提示的本地地址你会看到一个默认的Hello World页面。看到这页整个本地区块就算打通了。3.3 基本站点配置文件解读整个Hexo项目里最重要的文件就是根目录下的_config.yml很多新手改主题配置时容易把根配置和主题配置混淆。我建议把根配置看成全局设置把主题文件夹里的_config.yml看成皮肤设置。在根配置里你只需要重点关注几个字段site区域写标题、副标题、作者和语言url字段填你最终访问的站点地址如果配置了自定义域名就填自定义域名否则填GitHub Pages生成的地址deploy区域是部署目标。其他字段先用默认值跑通流程后面再慢慢优化。语言字段我建议改成zh-CN不然默认主题里一些内置文字会显示成英文。url字段有个细节如果填错或带上了奇怪的路径后面部署后文章链接和资源路径往往会多出一截路径导致样式丢失这点在常见问题部分还会细说。4. 从第一篇文章到本地预览4.1 写一篇文章需要了解的front-matterHexo使用Markdown作为书写格式但每篇文章开头都有一段叫front-matter的YAML配置它决定了文章的标题、日期、标签、分类和布局方式。最简单的写法是在source/_posts目录下新建一个.md文件开头这样写--- title: 我的第一篇博客文章 date: 2025-01-15 10:00:00 tags: - Hexo - GitHub categories: 建站 ---然后下面正常写Markdown正文。保存后执行hexo clean再执行hexo g文章就会被渲染成独立页面。需要注意title字段用于显示标题而文件名则参与文章链接的生成。如果文件名是中文链接会显示拼音或编码过的一长串字符介意美观的话建议把文件名写成英文或拼音标题写成中文即可。4.2 预览时要养成的几个习惯我平时写博客养成的最基本流程是写完后先执行hexo g再执行hexo s打开本地站点逐篇检查排版。本地预览看到的效果与线上基本一致。预览过程中打开浏览器开发者工具查看控制台报错能提前发现图片路径错、静态资源404等问题。这里分享一个我常用的技巧本地预览时可以再加上hexo server -w选项它会在文件变化时自动重新生成并刷新浏览器。写正文时不用来回手动开关命令改完保存浏览器自己就变了体验很接近动态博客。4.3 主题选择与常见定制默认主题足够跑通流程但如果想好看一点就需要更换主题。Hexo主题本质上就是一个文件夹里面是模板和样式代码。安装主题最稳妥的方式是去主题的GitHub仓库把仓库clone到themes目录下然后在根配置里把theme字段改成主题文件夹的名字。换主题以后排版和样式都变了但站点内容不受影响因为内容数据和外观是分离的。定制主题时我建议主要改这几处主题配置文件里的菜单、侧边栏头像、社交链接、页脚信息。不建议一上来就大改代码先用配置项把能调的都调了实在满足不了需求再动模板。5. 部署到GitHub Pages的完整过程5.1 创建GitHub仓库时注意命名规则这是整个流程里最需要小心的步骤。登录GitHub后新建一个仓库仓库名的格式必须是用户名.github.io。比如你的用户名是zhangsan仓库名必须精确写成zhangsan.github.io这是GitHub Pages识别个人站点仓库的硬性规则不遵守就无法通过默认地址访问。仓库建议选择Public公开可见因为Pages服务对公开仓库是免费托管。建好仓库后先不要勾选添加README文件保持仓库是空的新建状态这样后面推送时不容易出现两套不相关代码互相干扰的情况。5.2 配置deploy模块现在回到博客根目录打开_config.yml找到deploy部分把它改成类似下面的形式deploy: type: git repo: gitgithub.com:zhangsan/zhangsan.github.io.git branch: mainrepo地址建议使用SSH格式而不是HTTPS格式。SSH方式只要配置过密钥后续推送就不用反复输入账号密码。branch字段现在统一写main旧教程里有很多写master的那是早期默认分支名称不同导致的按现在的规范用main即可。配置好后需要安装一个部署插件npm install hexo-deployer-git --save这个插件是Hexo执行部署动作时用来调用git的桥梁不安装的话执行hexo d会直接报错提示找不到部署器。5.3 执行部署与验证网站配置完成后依次执行三个命令hexo clean hexo generate hexo deploy我一直习惯把clean放在生成之前因为每次改动主题或配置文件后public目录里可能残留旧文件不清理有时会出现改了半天没变化的假象。clean会删除public目录和之前生成的缓存数据库相当于把所有内容重做一遍。部署过程中终端会显示git的推送进度。看到类似master或main分支的推送输出后在浏览器访问你刚创建的仓库地址也就是用户名.github.io。第一次访问时偶尔会遇到404不用慌GitHub Pages开通需要几分钟时间默认分支可能会被自动切换到gh-pages分支这类问题我在下一节专门给排查清单。5.4 有自定义域名怎么配置如果你有自己的域名可以在仓库的Settings页面找Pages选项在Custom domain输入框填写你的域名。另外需要在域名管理后台添加一条CNAME解析记录把域名指向用户名.github.io。Pages开启后一般会自动申请免费HTTPS证书但有些情况需要手动点击Enforce HTTPS按钮让它生效。做好域名解析后记得去博客根配置里把url字段改成你的正式域名并在source目录中手动创建一个名为CNAME的文件文件内容就是你的域名。这个文件会被一起生成到public目录并推送到线上防止Pages端丢失自定义域名设置。6. 日常写作与多端同步6.1 如何在新电脑上恢复整个写作环境博客搭好之后最容易被忽略的就是换电脑连不上原来的环境。我在GitHub上专门建了一个私有的源码仓库用来保存整个工程目录。第一次搭建完成后把除node_modules和public以外的所有文件推送到这个仓库上之后每次写完文章也把源码一并推送。换电脑时只需要将仓库clone下来执行npm install重新安装依赖再执行hexo g和hexo s就又能继续用了。主题文件夹以及所有在themes目录里做的修改也都在源码仓库中保存不会丢失。如果不做这一步换设备后需要重新配置主题、重新写环境非常痛苦。6.2 图片素材的组织方式写博客必然要配图图片放哪里影响文章的可维护性。我采用的是Hexo官方建议的资产文件夹方式在根配置文件里将post_asset_folder设为true。这样每篇文章对应的图片会自动生成在同名文件夹里文章、图片放一起管理起来很直观。注意设置开启之后文章里引用图片要写成相对路径格式才能正确显示。相对路径的具体写法取决于主题对资产文件夹的支持情况个别旧主题不认这种路径时我会选择把图片统一放到source/images目录下然后在文章里用绝对路径根路径引用。不管哪种方式记得本地预览和部署后都要分别看一眼图片是否正常加载。6.3 修改、删除与置顶文章的管理方式动态博客里最平常的编辑操作在Hexo里其实就是直接改文件。要修改文章找到对应的Markdown源文件改完重新执行hexo g和hexo d即可。要删除文章直接删掉对应的Markdown文件再重新部署。要注意被删文件对应的public文件不会自动消失所以删除后执行一次hexo clean再生成避免旧页面残留。置顶文章没有内置的层级顺序功能最简单的办法是在文章front-matter里添加sticky字段sticky: 1数值越大排列越靠前。有些主题原生支持这个字段不支持的话可以给文章起数字前缀文件名手动控制排列顺序。7. 常见问题与排查实录7.1 访问用户名.github.io显示404这是部署后最常遇到的情况。第一反应检查仓库名是不是精确等于用户名.github.io一个字母都不能错。第二检查本地有没有真正生成public目录如果没有说明hexo generate执行失败过。第三检查仓库的Pages设置中Source是不是指向了main分支的根目录。我在早期部署时Pages默认分支有时会指向gh-pages分支而我的内容在main分支结果一直404手动改一下Source指向就好了。7.2 页面能打开但样式全乱页面能显示内容但布局完全崩溃十有八九是资源文件的路径不对。排查思路是打开浏览器开发者工具查看控制台里报404的资源请求观察请求的URL是否包含了奇怪的目录前缀。这种问题多是因为根配置里的url字段填错了导致Hexo生成静态资源引用时拼接出错误路径。检查url是否写成了类似http://localhost:4000或带子目录的形式改成最终线上地址后重新clean再生成。7.3 本地修改了内容线上却不变出现这种情况我会先确认自己是否执行了hexo clean。Hexo会生成缓存部分文件不更新时展示的还是旧内容clean后再generate基本能解决。其次检查文章有没有真的保存以及编辑器中是否出现了编码问题导致文章内容不可见。最后一种可能是推送了但没推送成功看终端输出的推送结果有时候分支写错会导致内容推到了其他仓库。7.4 上传文件时的常见误区很多刚接触Git的人不知道整个文件夹怎么上传老想着手动在网页端逐个点上传。我的建议是丢掉网页端的图形界面用git命令行操作。在工程根目录执行git add .、git commit -m 更新说明、git push origin main逻辑清爽且不会出现半途中断的问题。同理部署时用hexo d比手动复制public目录再上传要可靠得多那正是部署插件替你完成的自动化动作。7.5 部署插件报错的排查思路hexo d失败时先看终端里是否提示找不到deployer这表示没安装hexo-deployer-git。再确认部署配置里分支名是否准确仓库地址是否写错。如果提示认证失败说明SSH密钥可能没配好或者仓库地址写成了HTTPS格式但本机环境无法自动完成登录。遇到这类问题有个快速判断方法手动执行git clone仓库地址看能否顺利拉取内容能拉取就说明网络和认证都通问题出在Hexo配置上拉取失败就要先解决本地Git与GitHub之间的连接问题。8. 我对Hexo博客扩展方向的一些实际体会博客稳定运行之后你会发现静态站点的上限完全取决于你能往里面接什么服务。评论系统可以接入第三方评论服务只需在主题配置里填上仓库名或站点标识就能启用。浏览量统计、搜索功能、站内标签云这些都有对应的插件。但我的建议是先别贪多把基础写作和部署流程跑顺再逐步加一两个必需的功能。我个人在实际操作中最大的体会是Hexo搭建博客的门槛确实不高但前期一次性配好SSH密钥、规范化Markdown写作习惯、养成每次部署前clean一下的习惯这些小事能让你后面少踩八成的坑。这个内容后续还可以继续扩展的方向包括写一个自动部署脚本、把文章更新做成定时任务、用GitHub脚本在帖子发布时自动通知到其他平台等等。先把基础的上传、预览、部署动作养成肌肉记忆剩下的就都是水到渠成的事了。