如果你正在纠结要不要搭一个个人博客到底用什么方案我想先分享一个结论GitHub Pages加Hexo这套组合至今仍是我见过性价比最高的个人博客方案。我最早也试过租服务器跑动态站的路子后来被续费、备份、安全补丁这些事反复折腾最终把博客完全切到了这套静态方案上跑顺之后日常写字基本只碰两个命令省下来的精力全花在内容上。这篇文章会把当初踩过的坑和完整的落地流程都讲清楚从选型逻辑、环境准备、初始化、部署到主题定制和常见问题排查一条线走下来跟着做基本上一个小时左右就能让自己的博客在公网访问到。1. 选Hexo与GitHub Pages静态博客是被低估的长期选项很多人搭博客的第一直觉是租一台服务器装个WordPress或者Typecho。这条路本身没有错但你要承担的成本往往被低估了。服务器需要持续续费数据库要定期备份PHP和各类插件要盯紧版本和补丁一旦哪个月忘记续费或者懒得升级插件轻则数据丢失重则整站被挂马。我见过不止一个朋友因为这些问题最终放弃了维护博客死在了半年后某个忘记续费的清晨。静态博客的底层逻辑完全不同它本质上是把文章生成成一批静态HTML文件扔到任何能托管静态文件的地方就能跑。GitHub Pages恰好免费提供这种托管能力你只要把生成好的文件推到仓库里Pages会自动发布成公网站点。整个过程没有服务器、没有数据库、没有运维面板访问速度天然快因为每个请求都只是在拿一个普通文件而不是执行一段动态脚本。更重要的是可迁移性全站就是一堆文件哪天想换托管平台打包搬走就行不存在锁死问题。在静态博客生成器里我实际对比过几条主流路线。Jekyll虽然被GitHub Pages原生支持但依赖Ruby环境本地编译和依赖管理的体验在Windows上尤其别扭我折腾过一段时间后就放弃了。Hugo用Go编写构建速度快到夸张但主题和插件的生态规模要比Hexo小一圈社区中文资料也相对少。VuePress更适合写固定结构的文档站拿来做个人博客总觉得差点意思。Hexo刚好卡在最舒服的位置基于Node.js本质就是一个npm包安装没有任何隐藏依赖主题和插件数量是静态博客圈里的头部水平中文教程和踩坑贴多到搜不完。对于一个主要目标是专注写作的人来说这个生态成熟度非常重要。我最后选Hexo还有一个更现实的理由工具的复杂度和写作频率通常是反比关系。工具越简单你越愿意打开编辑器。Hexo的工作流真的可以压缩成一句话写Markdown跑一条命令生成再跑一条命令发布。没有可视化后台要维护没有插件市场要天天刷剩下的时间都是内容时间。下面这套流程就是基于这个选型展开的。2. 环境准备的三件事Node、Git和SSH钥匙开始之前先把三样环境备齐Node.js、Git、SSH密钥。很多人初始化Hexo时报一堆错回头看八成是这三者中有一样没弄干净。2.1 Node.js的版本选择和安装验证我建议直接装Node.js的LTS版本去官网下载安装包是最省事的方式。装完之后打开命令行输入node -v能正常打印版本号就说明环境没问题。这里有个很多人都栽过的坑电脑上如果有很老的Node比如12.x以下跑Hexo 6基本都会报错甚至直接装不上。我个人建议Node至少保持在16以上现在v18、v20这些LTS版本跑Hexo都很稳没必要追太新的奇奇怪怪的版本。2.2 Git安装与身份配置Git的安装同样是下载稳定版一路默认就行。装完最好第一时间配置两个全局参数否则后续的提交记录会带着一个错误的身份git config --global user.name 你的用户名 git config --global user.email 你注册GitHub时用的邮箱这里有个容易被忽视的细节GitHub判断一次提交是不是你靠的就是commit里的邮箱。如果邮箱和GitHub账号对不上你的提交不会关联到这个账号头像和贡献墙都显示不出来。等写了十几篇文章再回头改历史会非常痛苦所以这一步务必在一开始就配对。2.3 SSH密钥本地与GitHub之间的免密通道GitHub支持HTTPS和SSH两种仓库地址。HTTPS方式每次push都要输账号密码虽然可以缓存但在很多场景下还是会卡到人烦躁。SSH方式只需要配置一次密钥之后本地到仓库的推送全程免密这也是我推荐的方式。生成密钥的命令很简单ssh-keygen -t ed25519 -C 你的邮箱一路回车会在~/.ssh目录下生成一对文件id_ed25519是私钥id_ed25519.pub是公钥。然后打开id_ed25519.pub把内容复制到GitHub的Settings里的SSH and GPG keys页面新增一条SSH Key粘贴进去就行。验证是否配置成功ssh -T gitgithub.com如果看到一段欢迎语说明链路已经通了。换电脑时的场景我特别提醒一下新机器上最容易遗忘的就是这步。Git装好了、仓库也克隆下来了一提交发现没有权限先检查是不是忘了生成和配SSH密钥。密钥文件属于个人凭据不要放进任何工程目录里。3. hexo init之后目录结构、配置文件和博客骨架环境备好之后初始化Hexo其实非常快但很多人初始化完就开始懵——一堆目录和文件不知道哪个该改、哪个不该碰。这一节就把骨架彻底拆开讲清楚。3.1 初始化过程与命令建议用官方CLI工具来初始化而不是手动拼接npm install -g hexo-cli hexo init blog cd blog npm install第一行安装的是Hexo的命令行工具注意这里有个容易混淆的点hexo-cli是全局的命令入口而Hexo核心库会作为项目依赖安装到blog目录的node_modules里两者分工不同。不要手贱全局安装核心库否则后面项目依赖会乱成一团。hexo init会拉取一套完整博客骨架npm install把依赖装齐这时候项目已经可以生成和预览了。3.2 目录结构哪些文件需要管哪些不用管初始化完成后的目录长这样blog/ ├── _config.yml # 站点配置文件 ├── package.json # 依赖清单 ├── scaffolds/ # 文章模板目录 ├── source/ # 博客内容目录Markdown源文件都在这里 │ ├── _drafts/ # 草稿 │ └── _posts/ # 正式文章 └── themes/ # 主题目录我的建议是你日常真正需要操作的只有三个地方——_config.yml、source目录和scaffolds模板。package.json偶尔动一下就够themes目录在换主题时会用到。最容易被误操作的是后面生成出来的public目录它是每次构建的产物hexo clean之后会被完整删除在里面手工改任何东西都是白费功夫。3.3 站点配置文件的关键字段打开根目录的_config.yml有一批需要认真改的字段。我按优先级列一下字段作用建议title博客名称想一个简洁好记的名字subtitle副标题可选一句话补充description站点描述SEO和首页展示会用到author作者名会显示在文章底部和侧边栏language站点语言填zh-CNurl部署后的访问地址非常重要后面细说root站点根路径一般填/这里面url和root两个字段是重灾区。如果博客只放在GitHub Pages根路径url填你最终要访问的地址比如https://你的用户名.github.ioroot保持/就好。但如果以后想部署到子路径或者多级目录root一旦配不对主页能打开但所有静态资源的路径全都会错表现就是样式全乱、图片全挂。初期先把这两个字段和实际部署方式对齐可以少踩一个很大的坑。4. GitHub仓库和Pages让部署链路真正闭合Hexo生成的是静态文件但这些文件怎么变成公网可访问的博客关键在GitHub仓库和Pages的配置上。这里有非常明确的规则违反一个就可能404半天。4.1 仓库命名username.github.io规则GitHub Pages对个人主页有一套自动映射规则仓库名必须是你的用户名.github.io这种格式比如用户名叫somebody仓库就要叫somebody.github.io。只有这个名字Pages才会自动把它发布成https://somebody.github.io这个地址。我见过有人建了一个叫blog的普通仓库然后在Settings里翻半天找不到Pages入口其实就是卡在这个命名规则上。如果仓库名不是这个格式Pages功能也能开但域名会变成你的用户名.github.io/仓库名访问路径变长不说后续很麻烦。所以我强烈建议第一步就把仓库名取对。4.2 开启Pages与部署方式选择进入仓库的Settings找到Pages设置项。现在GitHub提供两种发布来源一种是从分支发布一种是从GitHub Actions发布。新手最简单的是从分支发布选择master分支的根目录保存即可。第一次发布通常需要等待一两分钟不要一直刷新页面以为失败了。发布完成后Pages页面顶部会显示你的博客地址看到绿色勾选状态就说明线上已经生效。4.3 本地一键部署配置虽然可以把构建生成的public目录手动拖进仓库但这种操作方式太过原始。更推荐安装官方部署插件让Hexo自己完成后台工作npm install hexo-deployer-git --save然后在_config.yml里补上部署配置deploy: type: git repo: gitgithub.com:你的用户名/你的用户名.github.io.git branch: master注意repo地址我建议用SSH格式就是gitgithub.com:...这种如果用HTTPS格式每次部署都需要重新验证账号体验很差。配置完以后发布博客就是一条命令的事hexo clean hexo g hexo dclean清理缓存generate生成静态文件deploy推送到GitHub仓库并触发Pages更新。这套手动流程对刚起步的人完全够用而且能让你理解每一环发生了什么。如果你更希望只要push源代码博客自己部署GitHub Actions自动化是更好的选择。需要在仓库里新建一个workflow文件示例配置如下name: Deploy Blog on: push: branches: [master] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm install - run: npx hexo generate - uses: peaceiris/actions-gh-pagesv3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./public publish_branch: gh-pages这个方案下你需要把Pages的Source切到GitHub Actions然后每次推送博客源文件Actions会在云端自动安装依赖、生成站点并部署。好处是本地不用再跑hexo d坏处是对新手来说调试成本高一些。我的建议很简单第一周先用手动部署把整个链路跑熟等流程理解了再切换到自动化不要一步到位。5. 主题装好只是开始配置与定制的关键决策Hexo默认主题非常朴素基本上没人会直接用。选对主题、配好主题博客的观感才能有质的提升。这也是整个过程中最让人兴奋也最容易踩坑的一段。5.1 主流主题选择和对比目前社区里活跃度高、文档健全的几款主题我实际用过之后可以给一个简单对比主题风格定位特点适合人群NexT经典学术风历史悠久、文档极全、插件兼容性好偏好简洁技术风的人Butterly现代卡片风功能丰富、颜值高、配置项多愿意花时间打磨细节的人Fluid清爽留白风首页布局干净、阅读体验好追求极简、重内容的作者选主题这件事我不建议盯着热门榜反复横跳。主题只是呈现层真正宝贵的是内容。选一个看起来顺眼、文档能看懂的然后用足够长的时间去熟悉它比每两周换一款主题有意义得多。我自己的博客从NexT换到Butterfly最后还是回到NexT原因就是折腾少、专注写作。如果你时间有限直接选NexT大概率不会后悔。5.2 主题安装与配置覆盖关系大多数主题的安装方式是克隆到本地。以我用的主题为例在博客根目录执行git clone 主题仓库地址 themes/主题名然后在站点_config.yml里把theme字段改成主题名重新生成就能看到效果。这时候你会接触到两套配置文件站点根目录的_config.yml负责全局参数而主题目录下的_config.yml负责主题自己的外观参数。很多小白在这里会晕不知道某个配置该改在哪一边。简单的判断标准是和SEO、站点信息、部署相关的是站点配置和布局、颜色、组件开关相关的是主题配置。有一个关键经验我必须单独说直接改themes/主题名/_config.yml虽然能生效但一旦主题更新、你拉取新版本所有改动都会被覆盖。更稳的做法是找一份主题配置的副本放在站点根目录或者至少把改动记录下来形成自己的配置文件每次升级完再重新应用。这听起来是小事但真有人因为没做这一步升级一次主题后博客外观彻底变了又花了一整晚调整。5.3 常用定制点主题装好后最常改的几个地方其实很固定导航菜单、侧边栏头像、社交链接、站点图标favicon。这些大多在主题配置里都有对应字段填上即可。更进阶的定制是给博客加功能模块我实测过比较实用的三个本地搜索、访问统计和内容复制保护可选。本地搜索需要安装hexo-generator-searchdb插件然后在主题配置里开启local_search这样站内搜索不用依赖任何第三方服务访问统计我用的不蒜子一段脚本引入即可轻量无侵入至于评论系统可选的方案很多但多数依赖第三方服务我倾向于建议新手先不折腾用邮箱和社交链接代替等博客有了一定访客量再加也不迟。6. 从hexo new到push一篇博文的完整生命线写作是博客的核心这个章节我们把一篇新文章从创建到上线的完整流程走一遍你会发现整个流程熟练之后两分钟就能完成。6.1 创建文章与Front-matter创建一篇新文章的命令是hexo new 文章标题这个命令会在source/_posts目录下生成一个Markdown文件并且根据scaffolds/post.md模板自动填入基础Front-matter。生成的初始内容一般只有title和date两个字段实际写作时通常要补上更多元信息。我常用的最小模板长这样--- title: 文章标题 date: 2024-01-01 10:00:00 tags: - 写作 - 博客 categories: 技术 cover: /img/cover.webp ---这里有个容易翻车的地方id、tags这类字段对格式极其敏感差一个冒号或者缩进整篇文章就可能渲染不了。好在Hexo生成时会把具体错误打印在终端里写好之后先本地预览看到报错顺着提示修就行比纯靠肉眼找错误舒服太多。6.2 写作、本地预览与调试写作本身直接用Markdown语法就行标题、列表、代码块、引用这些基础语法用熟已经覆盖绝大多数场景。写完一段之后强烈建议先本地跑预览hexo s然后浏览器访问localhost:4000改一行、刷新一下就能看到效果比推到线上再回看效率高一个数量级。需要调整端口时用hexo s -p 5000比如4000被其他程序占了的时候。本地预览阶段我发现一个常见现象文章里的图片路径有问题本地能显示但部署到GitHub Pages后就裂了。这个问题的根源多半是图片路径写成了本地绝对路径。如果你希望文章里可以引用本地图片最简单的办法是在站点_config.yml里开启post_asset_folder: true这样每次创建文章时会生成一个同名资源文件夹图片放进去用相对路径引用即可。6.3 发布流程与多设备同步本地预览满意后发布就是那条三板斧命令hexo clean hexo g hexo dclean很重要我建议不要跳过尤其是改过主题配置或调整过站点配置之后。不清缓存有时会继续部署旧的静态文件让你怀疑自己改了没用。发布成功后刷新线上地址新文章就出现了从创建到上线全程用不了几分钟。说到多设备写作这是博客维护里很现实的话题。如果只有一台电脑博客源文件只在本地一旦电脑出问题全部文章数据可能一起遭殃。我的做法是把整个博客目录放进一个私有Git仓库不是username.github.io那个公开仓库而是另一个私有的源文件仓库每次写完提交推上去。换电脑时git clone下来跑一次npm install所有环境就齐了。这个习惯的成本极低收益却是再也不怕电脑丢失。7. 淌过的坑与长期维护建议最后这部分是实战中积累下来的高频问题和维护经验每一个我都亲自踩过或排查过直接按症状、原因和解决办法列出来。7.1 高频问题排查症状根本原因解决办法发布后访问404仓库名不是username.github.io格式按命名规则重新建仓库在线页面打开样式全乱root或url配置错误检查站点配置文件确保root: /图片在本地好好的、线上裂了图片用了本地绝对路径开启post_asset_folder并使用相对路径或改用图床改了主题配置但是页面没变化没有清理旧缓存先跑hexo clean再重新生成部署时反复要求输入账号密码deploy.repo用了HTTPS地址换成SSH格式的仓库地址自定义域名后指向不正确CNAME文件被清理在source目录放下CNAME文件内容写你的域名这里再单独展开一个容易被人忽略的点如果你绑定了自己的域名CNAME文件要放到博客根目录的source文件夹里而不是直接放到本地生成目录的public里。因为public是清理重建的放在里面的CNAME每次都会消失放在source里才会在每次生成时被自动复制到产物目录并推送到线上。7.2 长期维护建议博客上线只是开始真正考验人的是怎么坚持写下去。我的几条实操建议是草稿模式要充分利用。写到一半的文章不要急着发布放到source/_drafts目录需要时用hexo server --draft做本地预览写完了再正式发布。这个机制能显著降低写作的心理压力不会因为没写完就发布而放弃更新。分类和标签要提前定好规则。一篇文章建议只归一个主分类标签控制在三到五个避免越写越乱。很多博客写了半年后首页一团乱麻问题不是文章质量而是元信息从一开始就没有规范。依赖升级要克制且定期。不必每个月追新版本但也不要几年不升。我一般半年左右执行一次npm update hexo和相关插件升级前会完整备份一遍源文件。静态博客最大的安全感是内容不依赖任何平台服务但前提是你别把依赖升级这件事拖到出了安全问题才想起来。还有很重要的一点任何对主题、配置文件的大改都先跑hexo clean hexo g做一次完整生成确认本地没问题再部署。别嫌多一条命令很多时候线上那点诡异问题就是省了这一步造成的。博客这个东西工具再花哨最终拼的还是内容和坚持。Hexo加GitHub Pages的好处就是它把基础设施的复杂度压到了极低让你把有限的精力全放在打字上面。希望这篇流程能帮你少走点弯路早点把第一篇文章发布出去。如果你搭建过程中在某个具体环节卡住了回头按这个顺序排查一遍大概率就能找到问题在哪。