做个人博客最让人上头的不是写了几篇文章而是每次打开首屏白屏时间从两秒多被压到零点几秒的那种爽感。我前前后后折腾过不少博客方案WordPress 功能全面但身子太重Hexo 插件丰富但依赖链太长换台电脑就要重新折腾 Node 环境后来在一个叫 colibri 的项目里找到了平衡点。这个名字源自法语和西班牙语里的“蜂鸟”我当时的诉求很明确——做一个加载极快、结构清晰、让我愿意持续更新的轻量级博客主题不堆砌功能不搞花哨动效把每一毫秒都花在刀刃上。这篇文章主要记录 colibri 从立项、改名、技术选型到落地优化的完整过程适合那些正在纠结“博客到底该用什么技术栈”“怎么把站点做得足够快”的朋友参考也适合单纯想看看一个个人项目能怎么一步步打磨的人。1. 为什么用蜂鸟命名从产品定位倒推技术决策1.1 蜂鸟的三个特征对应三种产品原则蜂鸟这种生物很特别它体型极小却能悬停在空中翅膀每秒能扇动几十次飞行方向灵活到可以倒着飞。如果给我的博客主题提炼三个关键词我会选“轻量、敏捷、精准停留”这正好和蜂鸟的习性对上了。轻量不引入无谓的依赖整个站点只输出必要的 HTML、CSS 和少量 JavaScript拒绝“为了用框架而用框架”。敏捷内容从写完到上线要足够快本地预览要快构建要快部署也要快不让人在等待中磨掉写作热情。精准停留读者进来之后能立刻看到文章的核心内容不被导航、弹窗、分享按钮干扰注意力精准地落在文字上。最初这个项目其实不叫 colibri我用的代号是 super-blog跟所有烂大街的模板项目一样毫无记忆点。后来做页面性能分析的时候看到蜂鸟扇动翅膀的高频视频突然意识到我要做的不是一只“更大的鸟”而是一只“更快的鸟”于是果断改了名。事实证明一个好名字能给项目带来方向感。每次我在功能取舍上犹豫的时候就会问自己一句“蜂鸟会这么干吗”大部分时候答案都很明确。1.2 明确用户画像避免功能蔓延产品定位清楚之后还要想清楚服务的人群。我做 colibri 不是为了服务“所有人”而是服务三类人一是像我一样每天写技术笔记的开发者二是偶尔写长文但不想折腾建站的独立创作者三是只阅读不写作的访客。这三类人的需求矛盾其实不小。写作者希望发布流程简单创作者希望排版好看阅读者希望加载快、不被打扰。很多博客平台最后做得又重又乱就是因为想同时讨好所有人结果每个角色都很不满意。所以我给 colibri 定了一个非常刻薄的功能边界凡是需要在页面里写超过二十行 JavaScript 才能实现的功能一律不做凡是能通过 CSS 优雅解决的效果绝不动用脚本凡是与阅读无关的模块默认不放在首屏。这套取舍原则导致 colibri 的功能列表短得可怜博客列表、文章页、归档、关于页、RSS 订阅加起来就这几样。评论区暂时不做搜索暂时不做多语言暂时不考虑。但我可以负责任地说对于一个以内容为核心的博客这套功能已经是够用的而且因为砍掉了那些沉重的模块整个站点的加载速度提升了不止一个档次。2. 技术选型的真实理由在速度与维护成本之间做取舍2.1 静态站点生成器对比我为什么选了 Hugo静态站点生成器SSG是个人博客的主流选择市面上比较常见的是 Hugo、Jekyll、Hexo、VitePress我在确定方案之前把这几个都摸了一遍列了一张对比表方案运行时构建速度依赖复杂度模板引擎适合场景HugoGo 编译出的单二进制极快千篇文章秒级几乎为零Go Template追求性能、内容量大的站点JekyllRuby中等文章多了会慢较多依赖容易冲突LiquidGitHub Pages 原生支持HexoNode.js中等多npm 依赖链长EJS/Swig插件生态丰富VitePressNode.js快但构建消耗更高中等Vue SFC / Markdown文档站、喜欢 Vue 生态我最后选了 Hugo核心原因有三个。第一Hugo 的默认构建速度惊人。我本地放了三百多篇测试文章Hugo 全量构建只要一秒钟左右Jekyll 和 Hexo 都会有明显的等待时间。写作频繁的人都知道预览响应越快改稿就越有耐心。第二Hugo 的安装和运行极度干净。它就是一个可执行文件不需要折腾 Ruby 版本、不需要维护 node_modules换电脑之后下载二进制就能跑这种确定性对于个人项目太重要了。第三Hugo 的模板和内容组织方式很符合“内容与样式分离”的理念。它把 Markdown 源文件、模板布局、静态资源各自放在独立目录里结构简单到可以复用很多年。2.2 Hugo 目录结构设计与内容组织思路colibri 的目录结构保持了 Hugo 官方推荐的形态但我在细节上做了适合自己的调整colibri/ ├── archetypes/ # 内容模板比如 posts.md 定义了 front matter 预设 ├── assets/ # 需要经过 Hugo Pipeline 处理的 CSS、图片 │ ├── css/ │ │ └── main.css │ └── images/ # 原始图片素材 ├── content/ # 所有的 Markdown 文章 │ ├── posts/ │ └── about.md ├── layouts/ # 模板布局 │ ├── _default/ │ │ ├── baseof.html │ │ ├── list.html │ │ └── single.html │ ├── partials/ │ │ ├── head.html │ │ ├── header.html │ │ └── footer.html │ └── index.html ├── static/ # 直接复制到根目录的静态文件 │ ├── favicon.ico │ └── robots.txt └── hugo.toml # 全局配置文件这个结构和官方默认差别不大真正的区别在内容组织思路上。我没有把站点做成“分类 标签 系列”三重维度而是只保留了两个posts/ 目录下面所有 Markdown 文件都是平铺的文章标签只是文章头部 metadata 里的一个字段不生成独立归档页。为什么这么干因为分类、标签、系列这三个维度很容易互相纠缠维护成本会指数上升。实际写作中单篇文章只需要一个日期、一个标题、一个摘要、一个标签列表平铺式管理最省心。2.3 为什么没有选择前端框架和 CMS很多朋友会问我“既然想要好的交互体验为什么不直接用 Vue/React或者直接上一个 Headless CMS 不也能很快”我对这个问题的回答是博客的场景决定技术形态而不是反过来。博客的绝大多数页面是服务端静态渲染的纯信息页面交互密度极低用户进来就是读文章、点链接、返回列表根本不需要一个维护大型状态管理的前端框架。引入 React 或 Vue 意味着引入 JavaScript 运行时、组件编译、路由管理等一大批复杂度第一次加载却拿不到任何实际收益。Headless CMS 我也认真考虑过它确实能解决“在手机上快速发文章”的需求但是它会引入二次构建、API 鉴权、数据同步等额外环节。对个人博客来说最稳定的发布链路反而是 Git 仓库加 Markdown在任何设备上写完commit 一下触发部署结束。这个流程没有中间态数据长时间不会丢失也不依赖第三方服务商是否还在运营。3. 核心页面设计与写作体验优化不堆功能只考虑阅读3.1 从一篇范文开始定义设计系统设计 colibri 的时候我没有先去调颜色、选字体而是先在 content/posts/ 里写了十篇样章包含不同长度的标题、多级小标题、代码块、引用、长段落、图片、表格。为什么要先有内容再设计因为页面结构必须服从内容形态脱离了真实文本去调样式出来的都是花架子。样章写完之后我反复阅读记录下阅读过程中踩到的每一个不舒服的点比如标题间距不够、代码块宽度溢出、行高太窄导致长句读起来费劲等等。基于这些真实阅读体验我建立了 colibri 的视觉基线正文字号设定在 17px 到 18px 之间行高 1.75段落间距用 margin 控制而不是靠空行。正文最大宽度控制在 68ch 左右避免在宽屏显示器上形成过长文本行。标题层级只用两级h2 作为大节标题h3 作为小节标题不出现四五六级标题从结构上倒逼我把文章组织得更清晰。代码块采用等宽字体背景使用低对比度的灰色不让代码抢正文的视觉重心。所有颜色都经过 WCAG AA 对比度检查深色模式单独调试避免切换后出现字体看不清的问题。这个设计没有追求“惊艳”要的就是“耐看”。博客的核心是文字花哨的设计只会增加认知负担。3.2 封面、列表与文章页的布局逻辑colibri 的首页列表摒弃了常见的“标题 日期”一行式列表改用卡片式布局但每张卡片都很克制包含文章标题、发布日期、一行摘要、标签。卡片由 CSS Grid 控制列数在移动端自动退化为单列。这个卡片并不复杂但解决了“信息密度”问题读者扫一眼就能判断哪些文章值得点进去。文章页的布局只有一个内容栏侧边栏彻底砍掉了。很多博客喜欢在侧边栏放热门文章、标签云、作者介绍看起来内容丰富实际上只会分散注意力。我的文章页从上到下依次是文章标题、发布日期、正文、底部导航上一篇/下一篇、一个极简版权声明。没有“猜你喜欢”没有“最新文章”没有弹窗订阅。这样的布局在第一次上线时确实显得有点“空”但使用一段时间后我越来越确信这种空恰恰是种保护。读者进来就是看内容看完就走干脆利落。3.3 写作体验的隐性优化Front Matter 与模板预设除了页面样式写作体验也是 colibri 的重要优化对象。我用 Hugo 的 archetypes 机制给每一篇新文章预设好了 Front Matter 模板新增文章时只需要运行hugo new posts/xxx.md文件里就会自动生成--- title: 文章标题 slug: date: 2025-01-15T10:00:0008:00 description: 一句话描述会显示在列表和搜索引擎结果里 tags: [] draft: true ---这样写文章的时候我只需要关心正文内容不用每次重复填写 metadata。尤其是description字段很多博客搭建者会忽略它导致社交媒体分享卡片和搜索结果里显示出很丑的默认摘要。colibri 在列表页和head里都读取了这个字段写文章时多花十秒钟填一句描述能显著提升页面的转发效果。另外我在模板里针对代码块做了一层额外的处理。Hugo 自带的高亮功能会把代码包装成很长的 HTML 结构我通过配置选择了基于 Chroma 的纯 CSS 高亮模式不生成任何 JavaScript这样代码块好看但不拖慢页面。4. 性能实测与移动端体验调优数据不会说谎4.1 用 Lighthouse 和 WebPageTest 建立性能基线colibri 上线后的第一件事不是庆祝而是跑一轮性能测试。我用 Lighthouse 在桌面端和移动端分别测试同时也用 WebPageTest 做了多地区测试拿到了一组基线数据指标桌面端移动端模拟慢速网络首次内容绘制FCP0.4s0.9s最大内容绘制LCP0.8s1.6s累积布局偏移CLS0.0010.001总阻塞时间TBT0ms10ms性能分数9998这个成绩不算顶尖但对于一个纯静态博客来说已经非常可观。能有这个结果主要不是因为我做了什么惊天动地的优化而是因为我一开始就选择了一条性能上限足够高的技术路线后面只需要把细节擦干净就行。我总结下来的三条核心性能策略第一不加载网络字体直接使用 system-ui 字体栈省掉字体文件下载和 swap 带来的文字跳动第二所有图片通过 Hugo 的图片处理功能压缩成 WebP 格式并按需生成多个尺寸移动端不会下载桌面端的大图第三CSS 文件不分割全部合并压缩成单个文件内联在 HTML 的head里避免额外的网络请求和渲染阻塞。4.2 移动端真正需要的优化点移动端优化有个容易忽略的误区不是光靠“响应式布局”就能解决所有问题真正的差别在资源加载策略。我拿手机访问 colibri 时做过一次实际的网络抓包发现问题主要集中在图片加载。原来自带的图片是 2500px 宽的 JPEG单张就好几百 KB在 Wi-Fi 下感觉不明显但切到 4G 网络就原形毕露。后面我通过 Hugo 的 image resource 处理把每张文章的封面图按照 480px、768px、1280px 三档尺寸输出并且在模板中用srcset配合sizes属性控制浏览器按需选择img srcset/img/post-480.webp 480w, /img/post-768.webp 768w, /img/post-1280.webp 1280w sizes(max-width: 600px) 100vw, 768px src/img/post-768.webp alt文章封面图 width768 height432 loadinglazy decodingasync /这里有个容易被忽略的细节图片的width和height属性一定要写不要省略。很多人会发现页面文字加载完的瞬间图片区域是空白的等图片加载完文字又猛地被顶下去这就是 CLS 的典型来源。只要 HTML 里声明了宽高比例浏览器在图片加载前就能预留对应空间布局偏移直接归零。移动端的第二根硬骨头是点击区域的尺寸。设计师在桌面浏览器上觉得“这个链接 14px 就够了”但到了手机上人类手指的精度远没有鼠标高。colibri 的导航链接、标签链接、分页按钮最小触摸区域都保证在 44px 以上。这个不是风格偏好是触屏设备的可用性底线。4.3 实测之后的一次“负优化”回滚优化过程中不是所有尝试都值得保留我也踩过回滚的坑。有一版 colibri 为了实现首页的阅读进度条引入了一个两百行的 JavaScript 插件。进度条确实很酷用户往下滑动时顶部会有彩色条显示阅读百分比但我在移动端测试后发现这个插件导致主线程的长时间任务增加TBT 从 0ms 涨到了 85ms而且滑动的流畅度有明显下降。我在体验和性能之间犹豫了两天最后决定把进度条去掉。反思之后我意识到这类装饰性功能带来的体验增益很难量化但性能上的损失是实打实的。一个博客的价值在于文字内容而不是用户能精确知道“我已经读了百分之几”这个功能值得被砍掉。类似被砍掉的功能还有图片灯箱、返回顶部按钮、分享到社交媒体的悬浮按钮。每个功能在单独看的时候都“很有必要”放到页面上才发现它们共同组成了一堆噪音。colibri 最终留在页面上的 JavaScript 只有一个用于实现移动端导航菜单展开的十行以内的小脚本其余全部是零脚本渲染。5. 踩过的坑与后续扩展方向给同样在做极简博客的人提个醒5.1 Hugo 升级带来的兼容性教训个人项目最容易忽略的就是依赖升级的兼容性问题。colibri 用的是 Hugo它本身是一个持续迭代的工具小版本升级通常是平滑的但跨大版本升级时很容易出问题。我在一次从 0.13x 升级到 0.14x 的时候站点构建直接报错排查了半天发现是新版本对某些模板函数的执行上下文做了更严格的校验我自定义的一个 shortcode 写法不再被支持。这事的直接损失不大但它让我建立了一个习惯每次升级前先看 release notes并且把升级前的版本号写进一个 CHANGELOG 文件里升级后用hugo --gc清理缓存并全量构建一次用 diff 对比生成的 HTML 是否出现异常变化。博客虽然是个小项目但凡是涉及线上更新的事都要有可回滚的预案。5.2 图片处理Hugo Pipeline 的边界与静态素材的取舍Hugo 的图片处理能力很强但它不是万能的。我在 colibri 中把放在 assets 目录里的图片通过resources.Get加载并调用.Process方法处理成多种格式这个流程在构建时可以把图片压缩得很好。但它的代价是构建时间变长尤其是图片很多或者原图很大的时候每次构建都要重新处理一张图累积的耗时很可观。对于偶尔才写一篇配图文章的人来说这个效率问题并不严重。但如果你计划高频更新我建议每次都先把原图压到 1600px 宽以内再放进 content 里不要依赖构建工具去处理 5000px 的超大原图。既节省构建时间也避免构建爆内存。Hugo 在图片处理时确实是先加载到内存再处理的超大图片在 CI 环境里可能直接导致构建失败。5.3 搜索、评论、多语言哪些功能可以晚点再要colibri 上线初期没有搜索功能开始我觉得没关系但文章数量超过一百篇后确实有读者反馈找历史文章不方便。我没有立刻引入外部搜索服务而是考虑了两套轻量方案第一套方案用 Hugo 预生成一个包含所有文章标题和摘要的 JSON 文件然后在前端放一个搜索框用 JavaScript 在本地执行简单的关键词匹配。这个方案适合中小型博客零服务器成本搜索速度也很快。第二套方案使用第三方搜索服务比如 Algolia 或者 Pagefind。Pagefind 是一个静态站点的离线搜索方案构建时生成索引搜索过程全部在前端完成不需要后端。它的精度比自写 JSON 匹配高配置也不复杂。我最后选择了 Pagefind因为它解决了一个自写方案很难解决的问题——中文分词。中文不像英文按空格分词自写的“包含判断”很容易出现奇怪的匹配结果Pagefind 内置了针对中文的分词支持体验明显更好。评论系统我到现在都没有接入。评论区本质上是一个需要后端、需要内容审核、需要反垃圾的复杂模块个人博客硬上评论功能会给自己找很多麻烦。如果哪天真的需要互动我更倾向于在文章底部放一个“欢迎邮件交流”的链接让沟通回归异步文字而不是在页面上挂一个需要维护的实时评论区。5.4 下一步内容才是 colibri 真正的主角现在 colibri 的代码和主题已经稳定下来我不会再往里面加大的功能模块了。后续的演进方向反而是内容层面的持续给 tag 建立更稳定的命名体系让归档可读性更高把更多旧笔记迁移到 colibri 的目录结构里形成统一的知识库条件成熟时再增加一个简单的英文版本同样以静态页面方式输出不引入国际化框架。一个博客项目能走多远很大程度上取决于它的技术门槛有多低、维护成本有多低。colibri 这个名字对我来说是一种提醒做一个像蜂鸟一样的站点身体轻巧反应迅速悬停在文字之上不打扰读者不拖累创作者。如果你正在规划自己的博客希望这篇记录能给你一些启发——先想清楚要砍掉什么再考虑要增加什么做一个轻巧、敏捷、精准停留的小站往往比做一个“什么都有”的庞然大物更值得。