个人博客搭建指南：从“blog测试”到Hugo部署上线

很多人写博客的第一步都是从一篇叫作“测试”的文章开始的。我当年也不例外域名买好、主题装好、系统跑通之后干的第一件事就是发了一篇名为“blog测试”的帖子内容只有一行字这是一篇测试文章。现在回头看那个瞬间其实意义不小——它代表一个属于自己的线上空间真正跑通了。这篇博文就顺着“blog测试”这个原点展开聊聊我是怎么从零折腾一个个人博客的包括技术选型怎么定、第一篇测试文章怎么发出去、上线之后又踩了哪些坑。无论是刚准备入坑的新手还是已经建好站但想优化维护流程的朋友应该都能找到能直接拿去用的东西。1. 在动手之前先想清楚博客要解决什么问题1.1 你的博客是给谁看的这个问题的答案决定了技术选型我见过太多人一上来就问“用什么框架好”“有没有好看的主题”但很少人先问自己一句这个博客到底是干嘛的这个问题不搞清楚后面每一步都可能白折腾。以我的观察个人博客基本逃不出三类场景。第一类是纯记录型博客只是一个数字化的笔记本写给自己看记录技术笔记、读书心得、生活琐事流量和美观都不重要重要的是写起来顺手、数据不丢。第二类是分享引流型希望通过文章获得搜索流量、读者关注甚至带来商业机会这类博客对SEO、加载速度、内容排版有硬性要求。第三类是折腾学习型建博客本身就是目的享受的是从选型到部署、从主题定制到性能优化这个过程博客就是最好的练手项目。你属于哪一类直接决定了你的技术选型。如果你只是记录那随便一个托管平台加一个在线编辑器就够了如果你想要流量那就要在生成静态页的效率和SEO友好度上做文章如果你是享受折腾本身那从服务器到代码托管都自己来也不为过。我自己的情况接近第二类和第三类之间——既希望文章能被搜索引擎收录又愿意花时间在博客本身的维护上。这个定位让我后来在很多交叉路口都做了相对明确的选择不至于反复推翻重来。1.2 内容优先还是技术优先一个容易走偏的坑建站过程中最容易犯的错误就是在技术上投入太多、在内容上投入太少。我身边就有朋友花了整整两个星期挑主题、调样式、装插件结果博客上线三个月只写了四篇文章。这其实和买了一堆高级厨具却天天点外卖差不多——工具的价值要由使用频率来体现。我的建议很简单先用最朴素的方式跑通一个能发文章的流程写够十篇再回头优化。不要一开始就追求完美因为你的审美和需求会在写作过程中慢慢改变提前投入的很多工作到时候都得推翻。而且只有开始真正写文章你才会知道自己到底需要什么功能——有人觉得评论系统必不可少写了一阵发现评论根本没几条有人觉得自己不需要标签分类文章多了之后才发现分类检索是刚需。这些认知只有通过实践才能获得光靠想象是规划不出来的。我自己当时就做了一件在别人看来有点反效率的事先用一套默认主题上线什么都不改专心写内容。等到写了将近二十篇之后我才开始比选主题彼时我心里已经有一个清晰的清单——需要什么样的布局、什么样的字体、什么样的配色。这份来自真实需求的清单让我的改版过程异常顺利。2. 技术选型静态站还是动态站我的选择和理由2.1 三类主流方案的对比一张表说清楚博客技术栈的讨论说到底就是围绕静态站和动态站的选择展开的。我用过不止一套方案中间也换过好几次各自的优劣基本都摸了一遍。下面这张表是我一直在用的对比框架给新朋友一个直观参考。对比维度静态博客生成器Hugo/Hexo动态博客WordPress/Typecho托管平台自带Notion Next等部署难度中等需要掌握命令行较低可视化安装极低绑定数据源即可写作体验Markdown 文件自由度高在线编辑器所见即所得数据源里写随处可写访问速度极快纯静态文件较慢依赖数据库和PHP中等视平台而定维护成本低无数据库无补丁高需定期更新核心和插件最低平台负责SEO 可控性高可精细控制每张页面中高靠插件补足较低受平台约束折腾乐趣很高中等几乎没有静态站的优点非常突出没有数据库、没有后台、没有安全补丁要打整站就是一堆预先生成好的HTML文件往任何静态托管平台一扔就能跑。这对一个以文字为主的博客来说已经足够。动态站的优势在于后台管理方便不需要懂命令行就能写文章但代价是需要一台能跑PHP和数据库的环境还要持续维护稍微松懈就可能成为被攻击的对象。托管平台自带方案算是最轻量的路径连代码部署都省了适合纯粹把博客当笔记本的人。但它的问题也很明显你被绑定在某一个平台上想迁走非常麻烦能自定义的部分也有限。如果你只是想写对技术不感兴趣这个方案反而是最省心的。2.2 我为什么在 Hugo 和 Hexo 之间选了 Hugo静态博客生成器里Hugo和Hexo是讨论最多的两个。Hexo基于Node.js插件生态丰富中文教程也多是很多人的入门首选。Hugo基于Go语言号称“世界上构建最快的静态站点生成器”一个几千篇文章的站点几十秒就能全部生成完。我最终选Hugo有几个很现实的原因。第一Hugo发布的是一个单二进制文件不依赖运行时环境不管在什么机器上都能跑换电脑也不需要重新装一堆依赖这对长期维护非常友好。第二Hugo的构建速度确实是碾压级的文章数量上来之后感受特别明显。第三Hugo内置了很多实用功能比如分类、标签、短代码、多语言支持等很多靠插件才能实现的东西它原生就有意味着少了一层维护负担。当然选Hugo也有代价。它的模板语法是Go Template和主流的前端模板不太一样熟悉需要一点时间。插件的数量也没有Hexo那么丰富有些功能找不到现成的就得自己写。不过对我这种需要长期维护且对速度有要求的场景来说Hugo的利远远大于弊。如果你是纯新手没有任何命令行基础Hexo反而更合适因为它的教程多、遇到问题容易搜到答案。工具从来不是越强越好而是越匹配越好。2.3 评论系统和数据统计也要提前想好很多人在规划博客时只想到“发文章”等到访问者来了才发现没有评论入口、看不到访问量。这两个模块虽然不直接影响写作却是博客闭环里比较重要的环节。评论系统我对比过三类。一类是依托GitHub仓库的Giscus和utterances原理是把评论内容存到GitHub的Issue里完全免费、无广告、不需要自建服务适合代码托管在GitHub上的技术博客。一类是自托管评论服务比如Waline数据在自己手里支持邮件通知、反垃圾等高级功能但需要额外部署一个后端服务维护成本会高一些。还有一类是第三方托管评论如Disqus接入最方便但要忍受广告而且国内访问体验一般。我选的是Giscus因为我的代码本身就在GitHub上评论和代码放一起管理起来很顺。数据统计方面我推荐一个叫 Umami 的开源方案可以自己部署数据所有权在自己手里没有Cookie弹窗的烦恼。如果不想为统计也搭一台服务用“不蒜子”这样极简的轻量脚本就够了几行代码就能显示页面访问量适合记录型博客。需要注意的是统计脚本不要一上来就接一堆否则不仅拖慢页面加载速度还会让访问者觉得隐私被过度收集。3. 从零搭建到“blog测试”文章上线的完整实操记录3.1 环境准备安装Hugo、新建站点、选一个主题这一节我直接给一套可以“抄作业”的流程。我的操作系统是macOS用Homebrew安装Hugo只需要一条命令brew install hugoLinux或Windows的用户也都有对应的安装方式Windows下用Scoop或者直接下载Release包都行。装完之后用hugo version验证一下看到版本号就说明环境没问题。接着初始化站点。假设你的项目目录叫mybloghugo new site myblog cd myblog执行后Hugo会生成一个基础目录结构里面有content文章目录、config.toml或config.yaml配置文件、themes主题目录等。这时候站点是空的连首页都打不开需要选一个主题装上。Hugo官网有一个很全的主题广场照着排行挑一个顺眼的下载下来放到themes目录下然后在配置文件里启用它git clone https://github.com/某用户/某主题.git themes/我的主题主题的名字和地址根据你实际选的来装好之后再回到配置文件把theme 我的主题这一项填上。这一步做完Hugo的基本骨架就算搭起来了。3.2 核心参数配置这些字段决定了博客的“地基”Hugo的配置文件是整个博客的中枢很多只会在日积月累中凸显出来的问题追根溯源都是配置没写好。下面是我认为需要重点关注的配置项以 TOML 格式为例baseURL https://你的域名/ languageCode zh-cn title 你的博客名称 theme 你的主题 [params] description 一句话描述你的博客 keywords [博客, 技术, 写作] [taxonomies] tag tags category categories [menu] [[menu.main]] identifier archives name 归档 url /archives/ weight 1这里面最容易被忽略的是baseURL和taxonomies。baseURL一定要填最终的线上地址否则生成出来的sitemap和RSS里的链接就全是相对路径或者错的域名搜索引擎收录时会出现一连串问题。taxonomies决定了你的标签和分类在系统中怎么组织如果不显式声明Hugo会使用默认配置倒也不会出错但想自定义的时候就会绕弯路。菜单的配置要看主题的脸色不同的主题菜单结构写法略有不同但基本都是围绕identifier、name、url这三个字段做文章。配置好菜单之后归档页、标签页才能在首页露出入口否则就得靠用户手动改URL才能访问到很不方便。3.3 写下第一篇“blog测试”文章并完成部署环境配好接下来就是最有仪式感的一步生成第一篇文章。Hugo的命令会自动创建带正确日期的Markdown文件比手动新建文件方便还不会搞错文件命名规范hugo new posts/blog-test.md打开这个文件你会看到类似这样的内容--- title: blog测试 date: 2025-01-15T10:00:0008:00 draft: true tags: [] ---这里有几个字段要说明一下。draft: true表示这篇文章还处于草稿状态构建时默认不会被发布等你看过预览没问题了就把它改成false。tags可以先留空也可以顺手加上“测试”“随笔”这类标签方便以后聚合。title就是文章标题我当年写的就是“blog测试”简单直接发给朋友看链接也能立刻知道这个博客跑通了。在正式发布之前先用本地预览看一眼效果hugo server -D终端会输出一个类似http://localhost:1313的地址浏览器打开它就能看到你的博客和那篇测试文章。-D参数的作用是让草稿状态的文章也在本地预览里显示出来别漏了。确定没问题之后退出预览把draft改成false然后生成正式的静态文件hugo --minify--minify会自动压缩HTML和CSS尽量减小文件体积。生成的静态文件在public目录里接下来把这些文件推送到任意一个静态托管平台就可以了。我最初用的是GitHub Pages流程是把整个项目包括源代码和public目录推到GitHub仓库然后在仓库设置里开启Pages并把发布目录指向public即可。如果用的是Cloudflare Pages或Vercel甚至可以在线关联仓库后交给平台自动构建发布省去本地手动构建的环节。3.4 发布后的自测清单这些地方不检查出问题你都不知道文章上线不代表万事大吉我给自己定了一个每次发布都必须过一遍的自测清单强烈建议你也这么做。第一用浏览器无痕模式打开博客首页和第二篇文章页确认页面没有异常报错。普通模式容易吃到缓存看不出真实效果。第二打开RSS订阅地址和sitemap.xml确认能正常解析这两个是搜索引擎和订阅工具的基础。第三检查文章页的标题、描述和关键词是否正确渲染到页面源码里这一步对SEO至关重要很多主题默认不输出描述需要手动确认。第四在手机上看一眼排版移动端的响应式布局出问题的概率远高于桌面端。第五如果有评论系统发一条测试评论确认整个评论闭环没问题。这一套检查做完一篇“blog测试”才算真正合格。具体的部署地址、仓库地址、评论配置等信息建议顺手记录在一个专门的文件里省得几个月后想更新却找不到部署入口。4. 上线之后日常维护、常见问题与踩坑记录4.1 一套内容发布SOP让每次更新都不费脑博客上线之后最需要建立的是一个固定的发布流程。这不是矫情而是实际操作中总结出来的经验——没有固定流程每次发文章都会东问一句西查一下非常浪费精力。我的发布SOP非常简单第一步在项目里写Markdown所有图片先压缩再放进static/images目录第二步本地跑hugo server -D预览一遍重点检查链接跳转和图片路径第三步确认无误后把draft改成false执行构建命令生成最新静态文件第四步用Git推送整个仓库托管平台检测到变更会自动部署第五步跑一遍上面说的自测清单。这套流程熟练之后从写完一篇草稿到线上发布全程不超过五分钟。关键在于把重复动作固定下来减少每一次的决策成本。还有一个我后来才养成的习惯在仓库里维护一个TODO.md有什么想写的选题、想做的功能先记下来避免灵感流失。4.2 常见问题速查表这些坑我基本都踩过博客维护过程中会遇到的问题大多集中在图片、缓存、构建和域名这几个方面。我把最典型的几个整理成速查表方便你遇到问题的时候直接对号入座。现象可能原因排查与解决方法页面样式错乱、布局全变了浏览器样式缓存了旧版本无痕模式打开或在部署后清一下缓存图片在本地能看到线上却显示不了图片路径是相对路径且图片没有进静态目录确认图片放在static/images里正文中使用/images/xxx.jpg绝对路径引用构建突然失败提示模板错误主题更新与Hugo版本不兼容查看报错信息定位模板文件更新Hugo版本或回退主题版本部署后一直是旧页面托管平台构建失败或Git推送未触发检查构建日志确认Git仓库的默认分支和平台设置的分支一致评论区无法加载或404评论系统配置的仓库名、路径或类型不匹配重新核对评论配置与仓库Category、Path等参数搜索收录一直没动静sitemap没提交或robots.txt屏蔽了抓取检查robots.txt向搜索引擎提交sitemap地址这个表里的问题我几乎都一个一个踩过。最让我记忆犹新的是图片路径问题本地预览好好的一上线图片全裂排查了半天才发现是路径少了开头的斜杠。还有一次升级了Hugo版本结果整个站点构建直接报错只能暂时回退版本。这类问题不会给你的博客带来致命打击但会让你在半夜修得很痛苦。4.3 坚持写作几年之后我对个人博客的几点体会博客这件事前面聊了很多技术细节但最后还是想分享一点技术之外的东西。我见过很多人花了很多精力装修博客最后却因为工作繁忙慢慢停更了。与之相反那些坚持得最久的人往往不是技术最强的而是把博客融进了日常生活节奏里的人。我个人的体会是不要给自己设定太高的更新频率目标。一周一篇对大多数人来说都太难了一个月能写一到两篇有质量的文章已经很不错。写博客是一种细水长流的输出需要找到适合自己的节奏慢慢积累而不是一开始就用力过猛几天热情过后就荒废了。另外博客里的内容哪怕开始只是技术笔记、生活随笔时间久了回头看都是一笔不大不小的财富。现在偶尔翻看自己早年写下的文章总会被当时的认真劲打动。博客的成长其实也是一个人的成长记录。如果你也准备开始搭建自己的博客我的建议是先别纠结工具直接用最简单的方式把第一个“blog测试”页面跑起来。第一篇文章发出之后你自然就知道下一步该做什么了。它不完美也没关系每一个持续更新的博客都是从一篇简简单单的测试文章开始的。