1. 写博客这件事为什么值得你亲手搭一个很多人一开始都想省事随手在公众号、知乎或者掘金上开个账号写两篇就完事了。我自己也走过这条路但时间长了你就会发现平台是平台的内容是内容的你辛辛苦苦写的东西规则一变、算法一改、账号一封说没就没。尤其是平台对敏感词、外链、排版格式的限制越来越多想放一段代码、插一张大图、自定义一个页面都得看平台脸色体验非常憋屈。所以大概三年前我开始折腾“个人博客系统”最后选了 Hexo GitHub Pages 这套方案。折腾下来最大的感受是真不难但也不是完全无脑。整个过程其实是“环境搭一次、命令记几条、内容天天写”的节奏新手最怕的是不知道每一步在干嘛一旦明白了底层逻辑剩下的就是复制粘贴。这篇就打算把我从零到一搭博客的全过程拆开讲。你不需要有编程基础只要会装软件、会复制命令跟着一步步走大概一两个小时就能拥有一个完全属于你自己的、能随时发文章的在线博客。适合谁看想写技术笔记的程序员、想整理读书笔记的学生、想给自己的简历加一个作品入口的职场人还有纯粹想在网上有一个干净写作空间的人都合适。顺带说一句这套方案最大的优点不只是免费而是所有文件都捏在你自己手里。纯静态文件用 Markdown 写部署到免费托管平台域名要是以后不想续费了换个托管商也只是一条命令的事永远不用担心平台跑路、数据被删。2. 搭建前的思路整理静态博客怎么选、为什么是 Hexo选博客方案之前先得搞清楚市面上的个人博客系统大概分几类。一类是动态博客典型代表是 WordPress。它需要服务器、数据库、PHP 环境功能非常全后台可视化编辑插件生态庞大但维护成本也高服务器要续费、系统要打补丁、数据库要备份小白的耐心很容易被磨光。另一类是托管平台像 WordPress.com、Notion 搭出来的公开页面零维护但定制空间小而且很多功能要付费。第三类就是静态博客生成器Hexo、Hugo、VitePress 都算。它做的事情其实很简单你用 Markdown 写文章它帮你套上主题模板生成一堆纯 HTML/CSS/JS 文件然后扔到托管平台上去就能访问。没有数据库、没有后台、没有服务器访问速度快得飞起安全风险也低到忽略不计。在静态博客的几款主流工具里我最终选了 Hexo原因有三个第一生态成熟。Hexo 是 2012 年就出来的老项目中文文档极其完善主题、插件多到用不完遇到问题随便一搜都有前人踩过坑的帖子。第二基于 Node.js对前端习惯比较友好就算你不懂前端装一个 Node.js 环境也就是点几下鼠标的事。第三部署流程简单一条hexo d命令就能把整个站推到托管平台不需要像 Hugo 那样了解额外的东西。我知道肯定有人会说 Hugo 构建更快、VitePress 更有现代感但对新手来说工具不是越强越好而是越好上手越好。Hexo 的学习曲线是“前陡后平”的只要前期环境装对了后面写作、部署完全是顺水推舟。数据上可以做个直观对比我之前用 Hugo 构建一个 100 篇文章的站点大概 0.8 秒Hexo 大概要 2 到 3 秒但这个差距对个人博客来说根本感知不到。反倒是 Hexo 的插件生态——比如hexo-generator-search、hexo-deployer-git、hexo-abbrlink——这些现成的东西帮我省了大量自己造轮子的时间。所以我的结论很直接如果你完全没接触过博客搭建只想省心、快速、后续好维护Hexo 是第一选择。等博客写到几十篇、对静态站点生成有了手感之后再考虑迁移到 Hugo 或者自己用框架定制都来得及。3. 环境准备装好 Node.js 和 Git半小时完成正式开始前先把“施工工具”备齐。Hexo 是基于 Node.js 的它要跑起来你的电脑上必须有 Node.js 环境。部署到托管平台要用到 Git版本管理工具也得装。3.1 Node.js 安装一路下一步就行去 Node.js 官网下载 LTS 版本也就是长期支持版。安装的时候一路 Next 就行不用改任何默认选项。下载链接、版本号这些细节官网都会自动推荐不用纠结选哪个默认的 LTS 就是最稳的。装完之后怎么确认装好了Windows 上按Win R输入cmd回车打开命令行Mac 直接打开终端输入node -v npm -v如果能看到类似v20.x.x和9.x.x这样的版本号说明环境没问题。这里稍微解释一下node是运行环境npm是包管理工具Hexo 本身、主题、插件全部靠它来安装所以这两个东西缺一不可。注意国内网络环境下用 npm 默认源安装包经常慢到怀疑人生。建议提前把 npm 源换成国内镜像。在终端执行npm config set registry https://registry.npmmirror.com之后所有安装操作都会快非常多。这一步不做后面装主题的时候很容易卡住大半天。3.2 Git 安装版本管理 部署钥匙Git 是干什么的用最通俗的话说它像你写作时的“存档系统”每次改动都能记录下来出问题可以随时回退。更重要的是Hexo 部署到托管平台这个动作本质上是往远程仓库里推送文件这个推送动作就是 Git 完成的。Git 的安装同样简单Windows 用户在官网下载安装包一路下一步Mac 用户装个 Homebrew 或者直接下安装包都行。装完在命令行里验证一下git --version能看到版本号就说明安装成功。这里插一句 Windows 用户的常见坑安装 Git 时安装向导会问“Adjusting your PATH environment”一定要保持默认的 “Git from the command line and also from 3rd-party software” 这一项不要改。否则后续在命令行里调用 git 可能会失败。我当初就是在这里走神点错了选项结果折腾了半个小时才反应过来。3.3 顺便换好 npm 源环境装好之后第一件事就是设置 npm 镜像源。这个操作不会影响任何功能只是把软件包的下载通道换成国内节点能帮你省掉大量等待时间。npm config set registry https://registry.npmmirror.com执行完可以输入npm config get registry看看是否已切换成功看到输出的是 npmmirror 的地址就对了。环境准备到这里就结束了。算下来其实就装了两款软件总共 10 分钟左右的事比想象中简单得多。接下来才是真正开始“搭建博客系统”的核心环节。4. 用 Hexo 初始化站点从零生成你的博客框架环境准备好之后就可以正式创建博客项目了。这个过程在 Hexo 里叫“初始化”一条命令可以拉出一个包含所有目录结构的完整项目骨架。4.1 全局安装 Hexo 脚手架首先在命令行里全局安装 Hexo 的命令行工具它负责帮你初始化项目、生成页面、启动本地预览npm install -g hexo-cli这一步会花一点时间耐心等它跑完。装完之后检查一下hexo -v能看到版本信息就代表脚手架装好了。这里解释一下-g后面的逻辑全局安装意味着你在电脑任何目录下都能直接敲hexo命令不需要进入某个特定目录再执行。4.2 初始化一个博客项目接下来选一个你喜欢的目录比如D:\blog或者~/Documents/blog然后在命令行里切换到该目录并执行hexo init如果你是新建一个空文件夹并且已经在其中打开了命令行直接执行即可。如果想让 Hexo 自动创建目录也可以hexo init blog它会生成一个叫 blog 的文件夹并初始化好全部内容。初始化完成后你会看到项目里多出来一堆文件和文件夹。新手看到这一堆东西很容易慌但别怕常用的就那几个source/_posts你所有的 Markdown 文章都放在这里这是你写作的主战场_config.yml博客的全局配置文件标题、关键词、主题、部署信息都在这一个文件里改themes存放主题文件的目录后面下载的主题都扔进这里package.json记录项目依赖和脚本命令一般不用手动改初始化完成之后先把博客跑起来看看效果。在项目根目录执行hexo clean hexo generate hexo server三条命令的含义分别是清理缓存、生成静态文件、启动本地服务。执行完第三条命令行会显示Hexo is running at http://localhost:4000用浏览器打开这个地址就能看到你的博客已经“活”了虽然还是默认主题、默认内容但架子已经搭好离上线只差最后几步。4.3 用官方文档默认配置打开部署之门看一眼项目根目录下的_config.yml用任意文本编辑器打开里面是博客的全局设置。最开头那块要把网站信息改成你自己的# Site title: 你的博客名称 subtitle: 一句话副标题 description: 两三句话描述你博客的内容方向 keywords: 关键词, 用逗号隔开 author: 你的名字 language: zh-CN timezone: Asia/Shanghaidescription和keywords这两个字段容易被忽略但它们直接影响搜索引擎收录时对你博客的定位判断。写清楚一点以后 SEO 能省不少事。语言和时区设置成中文文章时间显示就正常了。到这里“博客系统”的框架已经搭起来了。接下来进入下一个关键环节选一个好看的主题再把写作和发布流程理顺。5. 选主题、配主题让博客长得像你自己的默认主题 Landscape 是 Hexo 自带的风格非常朴素就像一个没装修的毛坯房。想让博客看得顺眼、有辨识度选一款合适的主题是必须的。Hexo 官方有一个主题列表按 Star 数排行比较主流的有 Next、Butterfly、Fluid、Icarus 等。5.1 主题怎么挑风格、维护活跃度和配置成本挑主题和挑衣服是一个道理首先要看风格对不对你的胃口其次要看维护是否活跃最后要看配置成本高不高。我个人推荐新手优先考虑 Butterfly 或者 Next。Butterfly 视觉效果现代卡片式布局、支持背景图、头像、顶部大图几乎不需要额外写代码就能调出一个精致好看的页面Next 则更偏向简洁排版流中文文档很全适合追求极致加载速度和“内容至上”的人。拿我自己举例我一开始用的是 Next简洁是简洁了但总觉得少了点味道。后来换了 Butterfly首页的 banner 图、分类卡片、归档页面改起来都很直观配置项都是中文注释对新手极其友好。主题的安装方式可以看各个主题的官方文档。以 Butterfly 为例在项目根目录执行git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly然后把_config.yml里的theme字段改成butterfly再重新执行hexo clean hexo generate hexo server刷新浏览器就能看到新主题的效果了。5.2 主题配置里值得改的几项每个主题都有自己的_config.yml一般位于themes/butterfly/_config.yml。里面配置项很多新手不用全部都改优先关注这几个站点菜单menu首页、归档、分类、标签、关于这几项按需开启即可侧边栏sidebar设置头像、社交链接、博客简介代码高亮主题深色还是浅色纯个人偏好评论插件后面我会单独讲不同插件配置方式有区别背景图和 banner 图找到banner相关配置项填上图片链接就行本地图片也可以放进source/img目录再引用还有一个小技巧主配置_config.yml里的url字段在部署之前一定要记得改成你最终的博客地址。很多人一开始不填或者填错了后面改域名会严重影响 SEO。5.3 配置完别忘重新生成主题改完必须重新执行hexo clean hexo g hexo shexo clean会清掉之前的缓存和静态文件这样才能保证新配置完全生效。很多人改了主题没反应十有八九是忘了 clean直接 generate 导致缓存没刷新。这是一个非常经典的新手坑先记住这个习惯每次修改配置后都先 clean 再生成。到这里博客的“面子工程”基本完成。接下来就是最核心的日常操作了怎么写文章、怎么处理图片、怎么发布。6. 写文章Markdown 语法和发布流程博客搭好了主题换好了接下来就是让它真正“用起来”的时刻。个人博客系统的日常使用说白了就是三件事写新文章、查看效果、发布上线。6.1 新建文章的两种方式第一种是命令方式。在项目根目录执行hexo new 我的第一篇文章Hexo 会自动在source/_posts目录下生成一个我的第一篇文章.md文件并自动填好头部信息。打开这个文件你会看到类似这样的内容--- title: 我的第一篇文章 date: 2025-01-01 12:00:00 tags: ---这个---包裹的部分叫 Front Matter是文章的元数据。title是标题date是发布时间tags是标签还可以加categories分类字段。第二种方式是直接手动创建.md文件同样放到source/_posts目录下头部格式照着写就行。自己创建的注意文件名最好用英文或拼音中文文件名在某些服务器环境下会出幺蛾子虽然大部分托管平台能处理但没必要给自己找麻烦。6.2 Markdown 书写要点Markdown 语法很简单半小时就能学会。个人写作最常用到的就是这几个符号#到######表示六级标题文章内小标题通常用##和###**加粗**用来强调重要内容 引用用来放引言或提示[链接文字](地址)和分别是链接和图片写作的时候还有一个很重要的概念叫“相对路径引用图片”。如果你把图片放在source/images目录下在文章里可以直接写这样图片会跟着博客一起打包上传不会出现图裂的情况。我自己的习惯是把所有图片统一放到source/images目录按文章名建子目录。这样做的好处是写文章时直接相对路径引用发布后不会再折返去维护图床之类的额外环节。6.3 本地预览与发布每写一篇文章想看看效果就执行一次hexo clean hexo g hexo s注意hexo g是hexo generate的简写hexo s是hexo server的简写日常操作用简写就行。浏览器打开http://localhost:4000会看到新文章已经出现在博客上。新文件不需要重启服务器保存刷新即可。到了要真正上线的时候把hexo s停掉终端里按Ctrl C然后执行hexo clean hexo g这一步生成的是最终要上传到服务器的静态文件它们会出现在项目根目录的public文件夹下。所有文章、主题、图片都被编译成了纯静态页面接下来只要把这个文件夹的内容扔到托管平台上博客就正式上线了。写作流程说到底就是“一条命令新建、一个编辑器写、三条命令发布”的循环。很多人觉得写博客麻烦主要是被环境搭建和部署劝退了真正进入写作期之后整个过程流畅得就像记日记一样。7. 免费部署上线把博客发布到全世界博客生成了静态文件现在就差“最后一步”把它放到一个随时能访问的托管平台上。对新手来说这里有一个关键选择是用 GitHub Pages还是 Gitee Pages或者其他平台。我先把两种主流方案都讲清楚。7.1 为什么优先推荐 GitHub PagesGitHub Pages 是 GitHub 提供的免费静态网页托管服务和 Hexo 的组合堪称绝配。它的优势有三点免费、无流量限制、支持 HTTPS。个人博客这种以文本为主的站点流量一般不大用它托管绰绰有余。使用步骤是这样的首先在 GitHub 上注册一个账号然后新建一个仓库。仓库名的规则很严格必须叫用户名.github.io比如你的用户名是zhangsan仓库名就是zhangsan.github.io。这个名字直接决定你博客的访问地址后续默认域名就是这个改不了。其次回到本地项目安装部署插件npm install hexo-deployer-git --save然后修改_config.yml最底部的deploy配置deploy: type: git repo: https://github.com/你的用户名/你的用户名.github.io.git branch: main如果 GitHub 仓库默认分支是 master那branch就填 master。现在新建仓库默认是 main具体看你仓库页面的提示。配错分支的话推送会失败这是一个很容易踩的坑。最后执行部署命令hexo dhexo d是hexo deploy的简写。它会自动执行代码提交并把public目录下的所有文件推送到远程仓库里。推送过程中可能会弹出 GitHub 的登录验证窗口按提示登录授权就行。等待十几秒命令行提示Deploy done然后打开浏览器访问https://你的用户名.github.io博客就正式上线了。7.2 Gitee Pages 的坑和适用场景国内常见的替代方案是 Gitee 码云它也有 Pages 服务而且服务器在国内访问速度比 GitHub 快但也存在几个不容忽视的问题第一Gitee Pages 需要实名认证没有实名认证开通不了。第二公开仓库的 Pages 服务在 2023 年之后需要手动审核才能上线每次更新文章都要重新审核一次非常影响发布体验。第三免费版对仓库大小有限制如果博客图片很多很容易超限。所以我的建议是优先用 GitHub Pages国内用户访问慢的话可以配合免费的 CDN 加速或者先托管在 GitHub再用国内云服务商的对象存储做图床把图片和页面源文件分离加载压力就小多了。7.3 独立域名值不值得买如果你觉得用户名.github.io这种地址不够专业可以去阿里云、腾讯云或 Cloudflare 买个域名后缀.com的一年几十块.top或.xyz的一年只要几块钱。然后把域名解析到 GitHub Pages 的 IP 地址在_config.yml里把url改成自己的域名就完成绑定了。这里提醒一句GitHub Pages 要求绑定的域名必须开启了 HTTPS否则浏览器会拦截。开通 HTTPS 并不难在仓库的 Settings - Pages 页面里勾选 “Enforce HTTPS” 就行GitHub 会自动帮你申请证书。整个过程十分钟能搞定。部署环节是整个建站过程里“成就感最强”的一步。看着自己写的文章从本地 Markdown 文件变成了全球可访问的网页那种感觉真的很奇妙。8. 进阶玩法SEO、评论系统和数据统计博客上线只是开始想让更多人看到你写的文章需要做三件事被搜索引擎收录、能接收访客互动、能看懂流量数据。8.1 SEO让搜索引擎找到你的博客新博客就像一间开在深巷里的小店Google 和百度得先知道它的存在才有可能把访客带过来。先做最基础的四件事。第一确保_config.yml里的description和keywords填好这是搜索引擎了解你博客内容的第一入口。第二在head里加上站点验证代码——如果要用百度站长平台它会给一段 HTML 标签让你贴到主题的head布局里跟着提示操作就行。第三生成 sitemap 文件安装插件npm install hexo-generator-sitemap --save重新执行hexo g你会发现public目录里多了一个sitemap.xml。这就是站点地图把所有文章链接都列了出来搜索引擎抓取时沿着它就能逛遍整个博客。第四去 Google Search Console 或者百度搜索资源平台提交你的域名然后等待收录。SEO 是一个见效慢但回报长期的事。不要急正常更新文章、保持内容质量大概一两周后搜索引擎就开始收录了。8.2 评论系统怎么选Hexo 没有自带评论功能需要接第三方评论系统。市面上主流的几个我帮你对比一下Valine 是一款基于 LeanCloud 的评论插件配置简单、界面干净对新手非常友好但默认情况下没有垃圾评论过滤功能需要自己后续在 LeanCloud 后台做安全设置。Giscus 是基于 GitHub Discussions 的评论系统没有数据库维护成本内容全存在 GitHub 仓库里稳定可靠但要求你的博客代码仓库和 Discussions 功能已经开启访客要登录 GitHub 才能评论。Waline 可以看作是 Valine 的增强版服务端部署需要一点后端知识不过有 Docker 一键部署方案适合喜欢折腾的朋友。我自己的选择是 Giscus。原因很简单我的博客仓库就在 GitHub 上直接在仓库设置里开启 Discussions然后按 Giscus 官网的引导生成配置代码粘贴到主题的评论配置里就完事了。不依赖任何国内服务商也不用担心实名认证和数据安全问题。8.3 数据统计用不蒜子还是 Umami博客访问量统计这件事细分下来有两种需求一种是“我想知道今天来了多少人”另一种是“我想在页面上给访客展示浏览量”。如果是后者最省事的方案是用不蒜子。在主题里开启相应配置页脚就会自动显示“本站访问量 xx 次访客数 xx 人”零成本、无需注册。如果是前者想认真分析访客来源、热力图、用户行为推荐用 Umami。它是一套开源的数据统计系统支持自托管部署到自己的 VPS 或托管平台上不采集用户隐私符合主流隐私政策要求。我在自己的博客上就装了 Umami能看到用户从哪来、看了哪些文章、停留多久对选题判断帮助很大。数据统计这件事新手阶段不建议过度关注。一开始访问量低是绝对的别被这个数字影响写作热情坚持输出有价值的内容才是核心。9. 常见问题与排查技巧实录我在搭建博客和帮朋友解决博客问题的过程中遇到过大量重复出现的报错和异常。这些问题的解决思路其实大同小异整理成一份排查手册可以直接对症下药。9.1 常见报错的完整排查表报错/现象可能原因解决方案hexo: command not foundhexo-cli 未安装或环境变量异常执行npm install -g hexo-cli重新安装如果是 Windows检查 PATH 中 npm 全局目录fatal: unable to access https://github.com/...网络无法访问 GitHub 或 git 未登录更换网络环境或配置 Git 代理确保 git 凭据有效YAMLException: end of the stream_config.yml格式错误注意冒号后必须加空格检查是否有中文标点混入主题修改后没生效未执行 clean 清理缓存执行hexo clean hexo g hexo s部署后文章不显示hexo d推错了分支检查_config.yml的 branch 字段是否和仓库一致图片在本地能看线上加载不出来图片路径错误或未随包上传使用/images/xxx.jpg绝对路径确认图片位于source/images目录页面样式错乱主题版本与 Hexo 版本不兼容查看主题文档确认支持的 Hexo 版本必要时升级或降级Duplicate meta tags报错多个 SEO 插件功能重复检查是否同时启用多个 sitemap 或 SEO 插件保留一个即可9.2 部署时“无变化可提交”的迷之现象有一次我执行hexo d终端提示成功但打开网页一点变化都没有。排查了半天发现原因是本地生成的静态文件时间戳比远程仓库的旧Git 认为没有改动拒绝提交。解决办法很粗暴先hexo clean再hexo g重新生成然后删掉仓库里的public目录或者直接从 git 层面强制推送hexo clean hexo g cd public git init git add . git commit -m update git remote add origin https://github.com/你的用户名/你的用户名.github.io.git git push -f origin main这种方式适合清理历史冗余 commit但不建议日常使用容易把仓库历史弄乱。遇到不更新的问题优先检查本地生成时间是否正常、远程仓库是否真的是最新代码。9.3 图片太多、加载太慢怎么办写了不少文章后你会发现图片迟早会成为一个问题。Hexo 打包图片是全部原样复制一张 3MB 的照片放进去页面加载就要好几秒。访问体验差不说GitHub Pages 的流量虽然免费但仓库建议不要超过 1GB。我的建议是用图床 对象存储的组合。把图片压缩到 WebP 格式尺寸控制在 1200px 宽度以内然后上传到对象存储服务文章里引用外链。这样博客本身的仓库体积始终保持在很小的范围部署速度极快页面加载速度也能大幅改善。对象存储的选择上各家服务商都有免费额度个人博客的量完全够用。配合 CDN 加速如 Cloudflare 的免费 CDN图片在全球范围都能秒开。9.4 域名出现“Site not found”或证书报错绑定独立域名后最常见的问题是Site not found或 SSL 证书不受信任。大部分情况是 DNS 解析还没生效。DNS 的生效时间从几分钟到 48 小时不等可以用ping 你的域名看看是否解析成功或者用在线 DNS 查询工具查解析记录是否指向了 GitHub Pages 的 IP。如果确认解析正确但仍然报证书错误去 GitHub 仓库的 Settings - Pages 里勾选 Enforce HTTPS等待几分钟让它自动签发证书就好了。注意GitHub Pages 的 SSL 证书签发需要几分钟到几个小时不等期间反复刷新不一定有用耐心等。10. 从博客上线到长期维护我愿意分享的全部心得文章写到这里整条搭建链路已经完整体验了一遍。从一个什么事都不懂的新手到拥有一套稳定运行的个人博客系统核心花费其实就三样一两个小时的耐心、一杯咖啡的时间和一点点对折腾的执着。说实话我在第一次部署成功后打开那个网址的瞬间是有一种“这真的是我做出来的东西吗”的恍惚感的。这种感觉是你在任何平台写文章都得不到的。因为这是你自己的小天地从结构到内容、从主题风格到每一条评论插件的配置都完全由你把控。关于长期维护我最后分享几个真实的经验。写作频率比写作长度重要。一开始我总想憋一篇“大文章”结果每周都写不出来后来改成每周固定发一篇一千多字的小总结流量反而涨得更快。搜索引擎和读者都更欢迎持续、稳定的更新。备份是第一位的。虽然 Hexo 的项目文件都在本地但电脑会坏、硬盘会丢强烈建议把整个项目目录推到一个私有的 Git 仓库里或者至少定期打包到网盘。我见过不止一个写了半年博客、结果硬盘坏了全丢的案例那种损失真的没法弥补。再小的一件事都值得用自动化去解决。比如我的博客现在部署直接用一条脚本搞定同时它会自动压缩图片、更新 sitemap、推送百度收录接口全程不需要手动干预。等你的博客文章多起来之后脚本带来的便利会成倍放大。如果你犹豫要不要自己动手搭一个博客我的建议永远是动手。搭建博客这个行为本身就是你对“创作”这件事的认真表态。你能亲手把一个空空如也的文件夹变成全世界都能访问的个人空间这件事带来的正反馈会支撑你写出越来越多、越来越好的内容。 用Hexo从零搭建个人博客：环境配置到免费部署全流程
1. 写博客这件事为什么值得你亲手搭一个很多人一开始都想省事随手在公众号、知乎或者掘金上开个账号写两篇就完事了。我自己也走过这条路但时间长了你就会发现平台是平台的内容是内容的你辛辛苦苦写的东西规则一变、算法一改、账号一封说没就没。尤其是平台对敏感词、外链、排版格式的限制越来越多想放一段代码、插一张大图、自定义一个页面都得看平台脸色体验非常憋屈。所以大概三年前我开始折腾“个人博客系统”最后选了 Hexo GitHub Pages 这套方案。折腾下来最大的感受是真不难但也不是完全无脑。整个过程其实是“环境搭一次、命令记几条、内容天天写”的节奏新手最怕的是不知道每一步在干嘛一旦明白了底层逻辑剩下的就是复制粘贴。这篇就打算把我从零到一搭博客的全过程拆开讲。你不需要有编程基础只要会装软件、会复制命令跟着一步步走大概一两个小时就能拥有一个完全属于你自己的、能随时发文章的在线博客。适合谁看想写技术笔记的程序员、想整理读书笔记的学生、想给自己的简历加一个作品入口的职场人还有纯粹想在网上有一个干净写作空间的人都合适。顺带说一句这套方案最大的优点不只是免费而是所有文件都捏在你自己手里。纯静态文件用 Markdown 写部署到免费托管平台域名要是以后不想续费了换个托管商也只是一条命令的事永远不用担心平台跑路、数据被删。2. 搭建前的思路整理静态博客怎么选、为什么是 Hexo选博客方案之前先得搞清楚市面上的个人博客系统大概分几类。一类是动态博客典型代表是 WordPress。它需要服务器、数据库、PHP 环境功能非常全后台可视化编辑插件生态庞大但维护成本也高服务器要续费、系统要打补丁、数据库要备份小白的耐心很容易被磨光。另一类是托管平台像 WordPress.com、Notion 搭出来的公开页面零维护但定制空间小而且很多功能要付费。第三类就是静态博客生成器Hexo、Hugo、VitePress 都算。它做的事情其实很简单你用 Markdown 写文章它帮你套上主题模板生成一堆纯 HTML/CSS/JS 文件然后扔到托管平台上去就能访问。没有数据库、没有后台、没有服务器访问速度快得飞起安全风险也低到忽略不计。在静态博客的几款主流工具里我最终选了 Hexo原因有三个第一生态成熟。Hexo 是 2012 年就出来的老项目中文文档极其完善主题、插件多到用不完遇到问题随便一搜都有前人踩过坑的帖子。第二基于 Node.js对前端习惯比较友好就算你不懂前端装一个 Node.js 环境也就是点几下鼠标的事。第三部署流程简单一条hexo d命令就能把整个站推到托管平台不需要像 Hugo 那样了解额外的东西。我知道肯定有人会说 Hugo 构建更快、VitePress 更有现代感但对新手来说工具不是越强越好而是越好上手越好。Hexo 的学习曲线是“前陡后平”的只要前期环境装对了后面写作、部署完全是顺水推舟。数据上可以做个直观对比我之前用 Hugo 构建一个 100 篇文章的站点大概 0.8 秒Hexo 大概要 2 到 3 秒但这个差距对个人博客来说根本感知不到。反倒是 Hexo 的插件生态——比如hexo-generator-search、hexo-deployer-git、hexo-abbrlink——这些现成的东西帮我省了大量自己造轮子的时间。所以我的结论很直接如果你完全没接触过博客搭建只想省心、快速、后续好维护Hexo 是第一选择。等博客写到几十篇、对静态站点生成有了手感之后再考虑迁移到 Hugo 或者自己用框架定制都来得及。3. 环境准备装好 Node.js 和 Git半小时完成正式开始前先把“施工工具”备齐。Hexo 是基于 Node.js 的它要跑起来你的电脑上必须有 Node.js 环境。部署到托管平台要用到 Git版本管理工具也得装。3.1 Node.js 安装一路下一步就行去 Node.js 官网下载 LTS 版本也就是长期支持版。安装的时候一路 Next 就行不用改任何默认选项。下载链接、版本号这些细节官网都会自动推荐不用纠结选哪个默认的 LTS 就是最稳的。装完之后怎么确认装好了Windows 上按Win R输入cmd回车打开命令行Mac 直接打开终端输入node -v npm -v如果能看到类似v20.x.x和9.x.x这样的版本号说明环境没问题。这里稍微解释一下node是运行环境npm是包管理工具Hexo 本身、主题、插件全部靠它来安装所以这两个东西缺一不可。注意国内网络环境下用 npm 默认源安装包经常慢到怀疑人生。建议提前把 npm 源换成国内镜像。在终端执行npm config set registry https://registry.npmmirror.com之后所有安装操作都会快非常多。这一步不做后面装主题的时候很容易卡住大半天。3.2 Git 安装版本管理 部署钥匙Git 是干什么的用最通俗的话说它像你写作时的“存档系统”每次改动都能记录下来出问题可以随时回退。更重要的是Hexo 部署到托管平台这个动作本质上是往远程仓库里推送文件这个推送动作就是 Git 完成的。Git 的安装同样简单Windows 用户在官网下载安装包一路下一步Mac 用户装个 Homebrew 或者直接下安装包都行。装完在命令行里验证一下git --version能看到版本号就说明安装成功。这里插一句 Windows 用户的常见坑安装 Git 时安装向导会问“Adjusting your PATH environment”一定要保持默认的 “Git from the command line and also from 3rd-party software” 这一项不要改。否则后续在命令行里调用 git 可能会失败。我当初就是在这里走神点错了选项结果折腾了半个小时才反应过来。3.3 顺便换好 npm 源环境装好之后第一件事就是设置 npm 镜像源。这个操作不会影响任何功能只是把软件包的下载通道换成国内节点能帮你省掉大量等待时间。npm config set registry https://registry.npmmirror.com执行完可以输入npm config get registry看看是否已切换成功看到输出的是 npmmirror 的地址就对了。环境准备到这里就结束了。算下来其实就装了两款软件总共 10 分钟左右的事比想象中简单得多。接下来才是真正开始“搭建博客系统”的核心环节。4. 用 Hexo 初始化站点从零生成你的博客框架环境准备好之后就可以正式创建博客项目了。这个过程在 Hexo 里叫“初始化”一条命令可以拉出一个包含所有目录结构的完整项目骨架。4.1 全局安装 Hexo 脚手架首先在命令行里全局安装 Hexo 的命令行工具它负责帮你初始化项目、生成页面、启动本地预览npm install -g hexo-cli这一步会花一点时间耐心等它跑完。装完之后检查一下hexo -v能看到版本信息就代表脚手架装好了。这里解释一下-g后面的逻辑全局安装意味着你在电脑任何目录下都能直接敲hexo命令不需要进入某个特定目录再执行。4.2 初始化一个博客项目接下来选一个你喜欢的目录比如D:\blog或者~/Documents/blog然后在命令行里切换到该目录并执行hexo init如果你是新建一个空文件夹并且已经在其中打开了命令行直接执行即可。如果想让 Hexo 自动创建目录也可以hexo init blog它会生成一个叫 blog 的文件夹并初始化好全部内容。初始化完成后你会看到项目里多出来一堆文件和文件夹。新手看到这一堆东西很容易慌但别怕常用的就那几个source/_posts你所有的 Markdown 文章都放在这里这是你写作的主战场_config.yml博客的全局配置文件标题、关键词、主题、部署信息都在这一个文件里改themes存放主题文件的目录后面下载的主题都扔进这里package.json记录项目依赖和脚本命令一般不用手动改初始化完成之后先把博客跑起来看看效果。在项目根目录执行hexo clean hexo generate hexo server三条命令的含义分别是清理缓存、生成静态文件、启动本地服务。执行完第三条命令行会显示Hexo is running at http://localhost:4000用浏览器打开这个地址就能看到你的博客已经“活”了虽然还是默认主题、默认内容但架子已经搭好离上线只差最后几步。4.3 用官方文档默认配置打开部署之门看一眼项目根目录下的_config.yml用任意文本编辑器打开里面是博客的全局设置。最开头那块要把网站信息改成你自己的# Site title: 你的博客名称 subtitle: 一句话副标题 description: 两三句话描述你博客的内容方向 keywords: 关键词, 用逗号隔开 author: 你的名字 language: zh-CN timezone: Asia/Shanghaidescription和keywords这两个字段容易被忽略但它们直接影响搜索引擎收录时对你博客的定位判断。写清楚一点以后 SEO 能省不少事。语言和时区设置成中文文章时间显示就正常了。到这里“博客系统”的框架已经搭起来了。接下来进入下一个关键环节选一个好看的主题再把写作和发布流程理顺。5. 选主题、配主题让博客长得像你自己的默认主题 Landscape 是 Hexo 自带的风格非常朴素就像一个没装修的毛坯房。想让博客看得顺眼、有辨识度选一款合适的主题是必须的。Hexo 官方有一个主题列表按 Star 数排行比较主流的有 Next、Butterfly、Fluid、Icarus 等。5.1 主题怎么挑风格、维护活跃度和配置成本挑主题和挑衣服是一个道理首先要看风格对不对你的胃口其次要看维护是否活跃最后要看配置成本高不高。我个人推荐新手优先考虑 Butterfly 或者 Next。Butterfly 视觉效果现代卡片式布局、支持背景图、头像、顶部大图几乎不需要额外写代码就能调出一个精致好看的页面Next 则更偏向简洁排版流中文文档很全适合追求极致加载速度和“内容至上”的人。拿我自己举例我一开始用的是 Next简洁是简洁了但总觉得少了点味道。后来换了 Butterfly首页的 banner 图、分类卡片、归档页面改起来都很直观配置项都是中文注释对新手极其友好。主题的安装方式可以看各个主题的官方文档。以 Butterfly 为例在项目根目录执行git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly然后把_config.yml里的theme字段改成butterfly再重新执行hexo clean hexo generate hexo server刷新浏览器就能看到新主题的效果了。5.2 主题配置里值得改的几项每个主题都有自己的_config.yml一般位于themes/butterfly/_config.yml。里面配置项很多新手不用全部都改优先关注这几个站点菜单menu首页、归档、分类、标签、关于这几项按需开启即可侧边栏sidebar设置头像、社交链接、博客简介代码高亮主题深色还是浅色纯个人偏好评论插件后面我会单独讲不同插件配置方式有区别背景图和 banner 图找到banner相关配置项填上图片链接就行本地图片也可以放进source/img目录再引用还有一个小技巧主配置_config.yml里的url字段在部署之前一定要记得改成你最终的博客地址。很多人一开始不填或者填错了后面改域名会严重影响 SEO。5.3 配置完别忘重新生成主题改完必须重新执行hexo clean hexo g hexo shexo clean会清掉之前的缓存和静态文件这样才能保证新配置完全生效。很多人改了主题没反应十有八九是忘了 clean直接 generate 导致缓存没刷新。这是一个非常经典的新手坑先记住这个习惯每次修改配置后都先 clean 再生成。到这里博客的“面子工程”基本完成。接下来就是最核心的日常操作了怎么写文章、怎么处理图片、怎么发布。6. 写文章Markdown 语法和发布流程博客搭好了主题换好了接下来就是让它真正“用起来”的时刻。个人博客系统的日常使用说白了就是三件事写新文章、查看效果、发布上线。6.1 新建文章的两种方式第一种是命令方式。在项目根目录执行hexo new 我的第一篇文章Hexo 会自动在source/_posts目录下生成一个我的第一篇文章.md文件并自动填好头部信息。打开这个文件你会看到类似这样的内容--- title: 我的第一篇文章 date: 2025-01-01 12:00:00 tags: ---这个---包裹的部分叫 Front Matter是文章的元数据。title是标题date是发布时间tags是标签还可以加categories分类字段。第二种方式是直接手动创建.md文件同样放到source/_posts目录下头部格式照着写就行。自己创建的注意文件名最好用英文或拼音中文文件名在某些服务器环境下会出幺蛾子虽然大部分托管平台能处理但没必要给自己找麻烦。6.2 Markdown 书写要点Markdown 语法很简单半小时就能学会。个人写作最常用到的就是这几个符号#到######表示六级标题文章内小标题通常用##和###**加粗**用来强调重要内容 引用用来放引言或提示[链接文字](地址)和分别是链接和图片写作的时候还有一个很重要的概念叫“相对路径引用图片”。如果你把图片放在source/images目录下在文章里可以直接写这样图片会跟着博客一起打包上传不会出现图裂的情况。我自己的习惯是把所有图片统一放到source/images目录按文章名建子目录。这样做的好处是写文章时直接相对路径引用发布后不会再折返去维护图床之类的额外环节。6.3 本地预览与发布每写一篇文章想看看效果就执行一次hexo clean hexo g hexo s注意hexo g是hexo generate的简写hexo s是hexo server的简写日常操作用简写就行。浏览器打开http://localhost:4000会看到新文章已经出现在博客上。新文件不需要重启服务器保存刷新即可。到了要真正上线的时候把hexo s停掉终端里按Ctrl C然后执行hexo clean hexo g这一步生成的是最终要上传到服务器的静态文件它们会出现在项目根目录的public文件夹下。所有文章、主题、图片都被编译成了纯静态页面接下来只要把这个文件夹的内容扔到托管平台上博客就正式上线了。写作流程说到底就是“一条命令新建、一个编辑器写、三条命令发布”的循环。很多人觉得写博客麻烦主要是被环境搭建和部署劝退了真正进入写作期之后整个过程流畅得就像记日记一样。7. 免费部署上线把博客发布到全世界博客生成了静态文件现在就差“最后一步”把它放到一个随时能访问的托管平台上。对新手来说这里有一个关键选择是用 GitHub Pages还是 Gitee Pages或者其他平台。我先把两种主流方案都讲清楚。7.1 为什么优先推荐 GitHub PagesGitHub Pages 是 GitHub 提供的免费静态网页托管服务和 Hexo 的组合堪称绝配。它的优势有三点免费、无流量限制、支持 HTTPS。个人博客这种以文本为主的站点流量一般不大用它托管绰绰有余。使用步骤是这样的首先在 GitHub 上注册一个账号然后新建一个仓库。仓库名的规则很严格必须叫用户名.github.io比如你的用户名是zhangsan仓库名就是zhangsan.github.io。这个名字直接决定你博客的访问地址后续默认域名就是这个改不了。其次回到本地项目安装部署插件npm install hexo-deployer-git --save然后修改_config.yml最底部的deploy配置deploy: type: git repo: https://github.com/你的用户名/你的用户名.github.io.git branch: main如果 GitHub 仓库默认分支是 master那branch就填 master。现在新建仓库默认是 main具体看你仓库页面的提示。配错分支的话推送会失败这是一个很容易踩的坑。最后执行部署命令hexo dhexo d是hexo deploy的简写。它会自动执行代码提交并把public目录下的所有文件推送到远程仓库里。推送过程中可能会弹出 GitHub 的登录验证窗口按提示登录授权就行。等待十几秒命令行提示Deploy done然后打开浏览器访问https://你的用户名.github.io博客就正式上线了。7.2 Gitee Pages 的坑和适用场景国内常见的替代方案是 Gitee 码云它也有 Pages 服务而且服务器在国内访问速度比 GitHub 快但也存在几个不容忽视的问题第一Gitee Pages 需要实名认证没有实名认证开通不了。第二公开仓库的 Pages 服务在 2023 年之后需要手动审核才能上线每次更新文章都要重新审核一次非常影响发布体验。第三免费版对仓库大小有限制如果博客图片很多很容易超限。所以我的建议是优先用 GitHub Pages国内用户访问慢的话可以配合免费的 CDN 加速或者先托管在 GitHub再用国内云服务商的对象存储做图床把图片和页面源文件分离加载压力就小多了。7.3 独立域名值不值得买如果你觉得用户名.github.io这种地址不够专业可以去阿里云、腾讯云或 Cloudflare 买个域名后缀.com的一年几十块.top或.xyz的一年只要几块钱。然后把域名解析到 GitHub Pages 的 IP 地址在_config.yml里把url改成自己的域名就完成绑定了。这里提醒一句GitHub Pages 要求绑定的域名必须开启了 HTTPS否则浏览器会拦截。开通 HTTPS 并不难在仓库的 Settings - Pages 页面里勾选 “Enforce HTTPS” 就行GitHub 会自动帮你申请证书。整个过程十分钟能搞定。部署环节是整个建站过程里“成就感最强”的一步。看着自己写的文章从本地 Markdown 文件变成了全球可访问的网页那种感觉真的很奇妙。8. 进阶玩法SEO、评论系统和数据统计博客上线只是开始想让更多人看到你写的文章需要做三件事被搜索引擎收录、能接收访客互动、能看懂流量数据。8.1 SEO让搜索引擎找到你的博客新博客就像一间开在深巷里的小店Google 和百度得先知道它的存在才有可能把访客带过来。先做最基础的四件事。第一确保_config.yml里的description和keywords填好这是搜索引擎了解你博客内容的第一入口。第二在head里加上站点验证代码——如果要用百度站长平台它会给一段 HTML 标签让你贴到主题的head布局里跟着提示操作就行。第三生成 sitemap 文件安装插件npm install hexo-generator-sitemap --save重新执行hexo g你会发现public目录里多了一个sitemap.xml。这就是站点地图把所有文章链接都列了出来搜索引擎抓取时沿着它就能逛遍整个博客。第四去 Google Search Console 或者百度搜索资源平台提交你的域名然后等待收录。SEO 是一个见效慢但回报长期的事。不要急正常更新文章、保持内容质量大概一两周后搜索引擎就开始收录了。8.2 评论系统怎么选Hexo 没有自带评论功能需要接第三方评论系统。市面上主流的几个我帮你对比一下Valine 是一款基于 LeanCloud 的评论插件配置简单、界面干净对新手非常友好但默认情况下没有垃圾评论过滤功能需要自己后续在 LeanCloud 后台做安全设置。Giscus 是基于 GitHub Discussions 的评论系统没有数据库维护成本内容全存在 GitHub 仓库里稳定可靠但要求你的博客代码仓库和 Discussions 功能已经开启访客要登录 GitHub 才能评论。Waline 可以看作是 Valine 的增强版服务端部署需要一点后端知识不过有 Docker 一键部署方案适合喜欢折腾的朋友。我自己的选择是 Giscus。原因很简单我的博客仓库就在 GitHub 上直接在仓库设置里开启 Discussions然后按 Giscus 官网的引导生成配置代码粘贴到主题的评论配置里就完事了。不依赖任何国内服务商也不用担心实名认证和数据安全问题。8.3 数据统计用不蒜子还是 Umami博客访问量统计这件事细分下来有两种需求一种是“我想知道今天来了多少人”另一种是“我想在页面上给访客展示浏览量”。如果是后者最省事的方案是用不蒜子。在主题里开启相应配置页脚就会自动显示“本站访问量 xx 次访客数 xx 人”零成本、无需注册。如果是前者想认真分析访客来源、热力图、用户行为推荐用 Umami。它是一套开源的数据统计系统支持自托管部署到自己的 VPS 或托管平台上不采集用户隐私符合主流隐私政策要求。我在自己的博客上就装了 Umami能看到用户从哪来、看了哪些文章、停留多久对选题判断帮助很大。数据统计这件事新手阶段不建议过度关注。一开始访问量低是绝对的别被这个数字影响写作热情坚持输出有价值的内容才是核心。9. 常见问题与排查技巧实录我在搭建博客和帮朋友解决博客问题的过程中遇到过大量重复出现的报错和异常。这些问题的解决思路其实大同小异整理成一份排查手册可以直接对症下药。9.1 常见报错的完整排查表报错/现象可能原因解决方案hexo: command not foundhexo-cli 未安装或环境变量异常执行npm install -g hexo-cli重新安装如果是 Windows检查 PATH 中 npm 全局目录fatal: unable to access https://github.com/...网络无法访问 GitHub 或 git 未登录更换网络环境或配置 Git 代理确保 git 凭据有效YAMLException: end of the stream_config.yml格式错误注意冒号后必须加空格检查是否有中文标点混入主题修改后没生效未执行 clean 清理缓存执行hexo clean hexo g hexo s部署后文章不显示hexo d推错了分支检查_config.yml的 branch 字段是否和仓库一致图片在本地能看线上加载不出来图片路径错误或未随包上传使用/images/xxx.jpg绝对路径确认图片位于source/images目录页面样式错乱主题版本与 Hexo 版本不兼容查看主题文档确认支持的 Hexo 版本必要时升级或降级Duplicate meta tags报错多个 SEO 插件功能重复检查是否同时启用多个 sitemap 或 SEO 插件保留一个即可9.2 部署时“无变化可提交”的迷之现象有一次我执行hexo d终端提示成功但打开网页一点变化都没有。排查了半天发现原因是本地生成的静态文件时间戳比远程仓库的旧Git 认为没有改动拒绝提交。解决办法很粗暴先hexo clean再hexo g重新生成然后删掉仓库里的public目录或者直接从 git 层面强制推送hexo clean hexo g cd public git init git add . git commit -m update git remote add origin https://github.com/你的用户名/你的用户名.github.io.git git push -f origin main这种方式适合清理历史冗余 commit但不建议日常使用容易把仓库历史弄乱。遇到不更新的问题优先检查本地生成时间是否正常、远程仓库是否真的是最新代码。9.3 图片太多、加载太慢怎么办写了不少文章后你会发现图片迟早会成为一个问题。Hexo 打包图片是全部原样复制一张 3MB 的照片放进去页面加载就要好几秒。访问体验差不说GitHub Pages 的流量虽然免费但仓库建议不要超过 1GB。我的建议是用图床 对象存储的组合。把图片压缩到 WebP 格式尺寸控制在 1200px 宽度以内然后上传到对象存储服务文章里引用外链。这样博客本身的仓库体积始终保持在很小的范围部署速度极快页面加载速度也能大幅改善。对象存储的选择上各家服务商都有免费额度个人博客的量完全够用。配合 CDN 加速如 Cloudflare 的免费 CDN图片在全球范围都能秒开。9.4 域名出现“Site not found”或证书报错绑定独立域名后最常见的问题是Site not found或 SSL 证书不受信任。大部分情况是 DNS 解析还没生效。DNS 的生效时间从几分钟到 48 小时不等可以用ping 你的域名看看是否解析成功或者用在线 DNS 查询工具查解析记录是否指向了 GitHub Pages 的 IP。如果确认解析正确但仍然报证书错误去 GitHub 仓库的 Settings - Pages 里勾选 Enforce HTTPS等待几分钟让它自动签发证书就好了。注意GitHub Pages 的 SSL 证书签发需要几分钟到几个小时不等期间反复刷新不一定有用耐心等。10. 从博客上线到长期维护我愿意分享的全部心得文章写到这里整条搭建链路已经完整体验了一遍。从一个什么事都不懂的新手到拥有一套稳定运行的个人博客系统核心花费其实就三样一两个小时的耐心、一杯咖啡的时间和一点点对折腾的执着。说实话我在第一次部署成功后打开那个网址的瞬间是有一种“这真的是我做出来的东西吗”的恍惚感的。这种感觉是你在任何平台写文章都得不到的。因为这是你自己的小天地从结构到内容、从主题风格到每一条评论插件的配置都完全由你把控。关于长期维护我最后分享几个真实的经验。写作频率比写作长度重要。一开始我总想憋一篇“大文章”结果每周都写不出来后来改成每周固定发一篇一千多字的小总结流量反而涨得更快。搜索引擎和读者都更欢迎持续、稳定的更新。备份是第一位的。虽然 Hexo 的项目文件都在本地但电脑会坏、硬盘会丢强烈建议把整个项目目录推到一个私有的 Git 仓库里或者至少定期打包到网盘。我见过不止一个写了半年博客、结果硬盘坏了全丢的案例那种损失真的没法弥补。再小的一件事都值得用自动化去解决。比如我的博客现在部署直接用一条脚本搞定同时它会自动压缩图片、更新 sitemap、推送百度收录接口全程不需要手动干预。等你的博客文章多起来之后脚本带来的便利会成倍放大。如果你犹豫要不要自己动手搭一个博客我的建议永远是动手。搭建博客这个行为本身就是你对“创作”这件事的认真表态。你能亲手把一个空空如也的文件夹变成全世界都能访问的个人空间这件事带来的正反馈会支撑你写出越来越多、越来越好的内容。