我折腾博客也有七八年了光是搭建方案就换过四轮从最早的虚拟主机加 WordPress到后来的 Hexo再到现在的 Hugo踩过的坑足够写满一个小本子。所谓个人博客本质就干三件事写文章、存文章、把文章发布出去让读者能看到。这三件事看似简单真做起来背后牵扯到静态生成器选型、Markdown 写作习惯、部署流程设计、图片资源管理、SEO 基础优化每一个环节都有讲究。这篇博文没有任何平台背景也不是什么教程翻译纯粹是我从零搭建个人博客全过程的记录和复盘。如果你正在考虑搭一个自己的博客或者已经搭好了但总觉得哪里不好用我相信这篇文章里的一些方案和教训能帮你少走弯路。我会把完整的选型思路、关键配置、部署流程、踩坑记录都拆开讲清楚尽量做到新手照着做也能跑通老手看细节也能有收获。1. 动手之前先想清楚需求拆解与整体方案选型1.1 三个核心需求写作体验、部署成本、长期维护我在重新规划博客之前先把过去几年用各种方案遇到的问题全部列了出来。以前用 WordPress 的时候最痛苦的就是三天两头要更新核心程序、插件和主题有时候早上起来打开后台发现界面变了查半天才知道是自动更新惹的祸。后来换到 Hexo本地要装 Node.js 环境一堆 npm 依赖动不动就版本冲突有一回升级主题直接让整个站点生成失败我花了一个周末才把问题解决。所以这次重新搭建我给自己的博客定了三个必须满足的核心需求。第一是写作体验必须纯粹我就想打开编辑器直接写 Markdown不要有任何后台界面、可视化编辑器、插件市场这些干扰。第二是部署成本要足够低我不想再为了一个博客单独买一台云服务器去维护最好能利用免费的静态托管服务访问速度和稳定性还不打折。第三是长期维护要省心选的技术栈必须足够成熟稳定就算几年不升级也不能出安全问题同时内容要能轻松迁移不能被某个工具锁死。这三个需求看似简单其实每一项都直接影响后续所有的技术选型。写作体验决定了要不要用静态博客方案部署成本决定了要不要选免费托管平台长期维护则要求整个链路尽量简单、依赖尽量少。1.2 平台对比静态博客生成器 vs 传统建站做过一次横向对比之后我基本可以确定一个结论对于个人博客这种以内容为主、交互需求极少的场景静态博客生成器是综合体验最平衡的方案。所谓静态博客生成器就是通过一个命令行工具把 Markdown 格式的文章源文件自动转换为纯 HTML 页面生成出来的是实实在在的文件没有数据库、没有后端程序托管到任何静态文件服务上都能直接访问。市面上主流的静态博客生成器有 Hexo、Hugo、Jekyll、VuePress、Astro 等各有各的侧重点。我一直用的是 Hugo主要看中它的生成速度极快几千篇文章也是秒级完成而且单二进制文件部署不依赖运行时环境这一点比 Hexo 的 Node.js 环境要省心不少。Jekyll 是 GitHub Pages 的原生支持方案配置简单但 Ruby 环境在国内网络环境下经常让人头大。VuePress 和 Astro 适合偏向 Vue 或前端组件化需求的场景对普通写作者来说有点重了。再说托管方案GitHub Pages 和 Cloudflare Pages 都是我实际验证过的稳定选择。GitHub Pages 的好处是跟代码仓库无缝集成直接推送分支就能自动发布缺点是对国内访问不够友好偶尔会出现样式加载慢的问题。Cloudflare Pages 的全球 CDN 节点让我这边和海外访问速度都比较稳定而且提供 Pages Functions 能实现一些简单的表单处理需求。最终我选择了 Cloudflare Pages毕竟免费额度完全够个人站点用还自带全站 CDN。1.3 为什么最终选了这套组合最后定下来的方案是 Hugo 加 Cloudflare Pages 加 GitHub 仓库。整个过程是在本地用 Hugo 写文章、生成静态文件推送到 GitHub 仓库备份Cloudflare Pages 检测到仓库变更后自动执行构建把生成的文件发布到全球节点。选这套组合有几个实实在在的理由。Hugo 的单一可执行文件特性让我在换电脑的时候完全不用重装环境下载解压就能用。GitHub 在我这边访问虽然不是特别快但只用来做版本管理和备份完全没问题而且天然提供了内容的历史记录改错了文章随时可以回滚。Cloudflare Pages 的构建配置我只需要写几行命令它自动识别 Hugo 项目并且缓存处理做得不错部署一次之后后续更新全自动我只需要专注写文章这一件事。这里还有一个很容易被忽视的点就是整套方案的迁移成本几乎为零。Hugo 的内容文件就是带元信息的 Markdown 文件哪天我不想用 Hugo 了直接把content目录搬到任何其他静态博客生成器里适配一下元信息格式就能完成迁移。这种自由度对我来说比任何花哨的功能都重要。2. 本地环境准备与基础配置2.1 需要准备的工具清单基于我上面选定的方案你只需要准备四个工具就能完成全部搭建工作分别是 Git、Hugo、一个代码编辑器和一个 Cloudflare 账号。Git 负责版本管理和代码推送这个是静态博客工作流里绕不开的基础设施。Hugo 就是博客生成器本身我建议直接用包管理器安装macOS 可以用 HomebrewWindows 可以用 Chocolatey 或 ScoopLinux 系可以直接下载对应发行版的二进制包。代码编辑器我一直在用 VS Code它自带的 Markdown 预览插件很好用左边写右边看效果配合 Markdown All in One 这个插件还能自动生成目录和快捷键格式化表格。如果你是初学者建议也装一个 Typora 作为辅助预览工具Typora 的所见即所得模式能让刚接触 Markdown 的人迅速建立起语法认知等熟悉了再回到 VS Code 也完全没问题。需要特别提醒的是Cloudflare 账号注册之后建议把两步验证开起来这跟博客本身关系不大但托管了你的代码构建权限安全问题还是值得重视的。我自己的账号就绑定了一个单独的邮箱跟日常使用的邮箱做了隔离万一日后某个平台出点泄露之类的状况不至于波及博客项目。2.2 初始化博客项目的完整流程工具准备就绪之后第一次初始化项目建议从头到尾走一遍把每个命令的作用弄清楚。打开终端先确认 Hugo 已经安装好然后创建一个新站点。站点名称就用你的博客名字我当时的命令是hugo new site my-blog cd my-blog这个命令会生成一个目录结构里面content目录放 Markdown 文章layouts目录放自定义模板static目录放图片等静态资源config.toml或hugo.toml是全局配置文件。第一次看到这个结构的直觉感受可能是目录挺多但真正常用的无非就是content和static这两个。接下来要选择一个主题这一步我说的经验是千万不要一上来就陷入主题选择的泥潭里。Hugo 官方主题列表上有几百个主题我见过太多人挑主题挑了半个月还没开始写文章。我的建议是先选一个文档完善、最近还在维护的主题用起来等博客跑通了、内容积累到一定程度再考虑换主题的事情。初始化完成之后把项目关联到 GitHub 仓库这里有个操作顺序容易搞错。我建议先在 GitHub 上建一个空仓库然后执行下面的初始化推送git init git add . git commit -m Initial commit git branch -M main git remote add origin 你的仓库地址 git push -u origin main推送成功之后再在 Cloudflare Pages 控制台里新建项目选择关联这个 GitHub 仓库。Cloudflare 会引导你配置构建命令Hugo 项目的构建命令是hugo --minify发布目录是public。我强烈建议在构建环境变量里加上HUGO_VERSION值填你本地的 Hugo 版本号比如0.121.0这样能确保线上构建和本地生成结果绝对一致避免版本差异导致的样式或者内容偏差。2.3 关键配置文件详解Hugo 的配置文件是整个博客的神经中枢很多新手觉得配置项太多太杂其实只需要关心几个核心参数。我的习惯是把配置文件从默认的hugo.toml改成 YAML 格式对我来说可读性更好这里我展示一下我的基础配置baseURL: https://你的域名/ title: 你的博客名称 languageCode: zh-cn theme: 你选的主题 pagination: pagerSize: 10 enableRobotsTXT: true build: writeStats: true markup: goldmark: renderer: unsafe: true其中baseURL一定要填最终要使用的完整域名如果填错了后续生成的页面里所有链接都会指错地方。languageCode改成zh-cn能让浏览器和搜索引擎正确识别页面语言对 SEO 有基础帮助。enableRobotsTXT会生成 robots.txt 文件让搜索引擎明确知道哪些路径可以抓取。markup.goldmark.renderer.unsafe这个配置我单独说一下它允许在 Markdown 文章里直接写原生的 HTML 标签。默认情况下 Hugo 会把 HTML 标签原样转义显示开着这个配置之后你能在文章里嵌入一些自定义的样式和交互组件比如我自己就在文章里插入过视频嵌入代码和自定义的提示框。风险是如果文章内容不可信可能会引入 XSS 问题个人博客自己写自己发问题不大多作者博客就建议谨慎开启。3. 核心环节文章写作与部署发布3.1 用 Markdown 写文章的正确姿势静态博客的核心操作就是写 Markdown 文件Hugo 对 Markdown 的支持走的是 CommonMark 标准再加上一些扩展语法。写文章的时候需要掌握的不过是标题、加粗、斜体、链接、图片、代码块、列表和引用这几种最基础的语法只要写了三四篇自然就熟练了。我个人的习惯是先用草稿模式创建文章Hugo 的命令是hugo new posts/我的第一篇博客.md需要注意文件名会直接成为文章的 URL 路径所以建议用英文和数字命名比如my-first-post.md中文文件名虽然也能用但生成的 URL 会经过转义变得又长又丑对分享和 SEO 都不友好。文章的中文标题放在文件开头的元信息里就行这样功能和展示完全分离。Hugo 的 Markdown 文件开头有一段用三个短横线包裹的元信息区域通常叫 front matter里面至少要有title和date这两个字段。我的模板会把tags、categories也留出来写作的时候就顺手填上避免事后补标签还要重新生成。第一次写文章的时候可以把draft: true加上这样本地预览能看到但正式构建不会发布出去适合半成品文章的保存场景。3.2 文章元信息与归档逻辑文章的元信息直接影响博客的分类归档和内容组织。我一开始把所有文章都平铺在一个目录里后来文章数量过了五十篇之后查找和整理极不方便就按照年份和主题做了重新归档。Hugo 的content目录结构直接决定了 URL 结构比如content/ posts/ 2024/ my-first-post.md 2025/ build-blog-guide.md这样的结构生成出来的 URL 是/posts/2024/my-first-post/看起来结构清晰层次分明。如果你的内容涉及几个明确的主题分类那就在posts下面再建分类目录但不要嵌套太深两层就够了。嵌套超过三层之后 URL 会变得很长后台管理和手动维护都会很麻烦。归档逻辑这块还有一个容易被忽略的地方就是标签和分类的数量要克制。我刚开始写作的时候每篇文章恨不得打上七八个标签觉得这样才能增加曝光。后来看统计发现标签太分散反而让读者抓不住重点一个标签下面只有一篇文章也起不到关联阅读的作用。现在我的原则是一篇文章不超过三个标签分类只有一个保持内容组织的清晰度。3.3 从本地到线上部署流程实操完整的部署流程分成本地预览、提交推送、自动构建、验证访问四步。本地预览是我每次必做的尤其是改动过导航栏、首页布局或者样式文件之后一定要起本地服务检查效果hugo server -D-D参数的意思是包括草稿文件一起显示方便在本地看到所有未发布的文章效果。浏览器访问http://localhost:1313就能实时预览每次保存文件页面会自动刷新这是整个写作流程里体验最顺滑的环节。确认本地没问题之后把修改提交并推送到 GitHub这里我使用的是带-am参数提交能同时暂存所有修改并附上提交信息git add . git commit -m Add new post: 我的第一篇博客 git push推送完成之后Cloudflare Pages 会自动检测到仓库变更并触发构建流程整个过程通常在几十秒内完成。你可以在 Cloudflare Pages 控制台的部署日志里看到构建进度全部步骤变成绿色之后打开线上网址确认文章已经发布。这里我要说两个我在实际操作中遇到的容易混淆的概念。一个是永远不要在本地仓库里直接改public目录生成的内容因为它是构建产物每次构建都会被覆盖正确做法是改源文件然后让构建流程重新生成。另一个是 Cloudflare Pages 的域名绑定问题如果你用默认提供的*.pages.dev域名国内部分地区访问可能不稳定建议绑定一个自己的域名并在 Cloudflare 里开启代理模式这样才能获得完整的 CDN 加速效果。4. 常见问题与排查技巧实录4.1 本地预览正常但发布后样式丢失这个问题我遇到过而且很有意思本地打开一切完美部署到线上之后页面变成了纯文本加无序列表。排查了一圈发现是配置文件的baseURL还是默认值导致的主题文件里引用的 CSS 和 JS 资源都用绝对路径拼的baseURL本地预览的时候 Hugo 会用临时地址覆盖这个值看起来没什么问题但线上构建用的是配置文件里的值配错了所有资源的路径就全部失效。排查流程很简单按顺序验证第一看浏览器开发者工具里 CSS 文件请求的完整地址是什么状态如果是 404 或者指向了奇怪的域名十有八九是baseURL配置错误。第二看 Cloudflare Pages 的构建日志中有没有资源文件复制失败的警告。第三确认是不是主题要求的 Hugo 最低版本没有被满足部分新主题会用到比较新的模板语法老版本生成结果会残缺不全。这类问题解决起来都不难但排查过程教给我一个原则生产环境和本地环境任何一处配置不同都有可能导致线上结果异常。所以我在本地测试完毕之后会专门跟线上配置做一次对比确认环境变量、构建命令、发布目录这些关键参数完全一致再推代码。4.2 图片加载慢与资源路径问题图片处理是静态博客里最容易被低估的环节。我的一篇文章里如果放了四五张截图每张图片原始大小都有一两兆的时候整个页面的加载时间会明显变长。第一次发现这个问题是有读者留言说打开文章很慢我自己测了一下才发现光图片就占了页面总体积的八成以上。现在的处理方式是图片全部要先压缩再入库jpg 格式图片的质量参数压到 80 左右PNG 格式如果没有透明需求尽量转成 jpg。截图类图片分辨率高但颜色简单的可以用工具压缩到原来的十分之一大小肉眼几乎看不出画质损失。Hugo 本身就内置了图片处理函数可以在生成页面的时候自动生成指定尺寸的缩略图对于同一张图在列表页和文章页不同尺寸展示的场景非常实用。图片资源路径的坑相对隐蔽一些我在重构目录结构的时候大意过一回导致旧文章的图片全部失效。Hugo 的静态资源路径有两种引用方式一种是放到static目录下直接用绝对路径引用另一种是放到文章同级的目录里用相对路径引用。我现在的项目全部采用前者把图片统一放在static/images目录下然后按年份和分类建子目录。这样的话就算文章重新归档只要不清理static目录里的图片路径就不会乱。4.3 评论区功能的选择与踩坑很多博主搭好博客之后第一件事就是想加评论区我一开始也是这么想的。传统的评论区方案大概有三条路线一种是用第三方评论服务像 Disqus、Gitalk另一种是自建后端评论系统还有一种是利用静态托管平台提供的轻量功能。Disqus 功能齐全但加载脚本偏重且服务在国外国内打开会拖慢页面速度。Gitalk 基于 GitHub Issues 实现国内访问 GitHub 的 Issues 页面有一定延迟而且要求读者有 GitHub 账号才能评论门槛偏高。我刚上线博客的时候试过 Gitalk结果踩了一个挺隐蔽的坑。有个读者反映评论一直初始化失败我自己测试了半天才发现问题出在 GitHub OAuth App 配置的回调地址上。原来 HTTPS 和 HTTP 协议不同、带不带www前缀都会被严格审查匹配凡是有一个不匹配就直接拒绝回调。后来又了解到 Gitalk 还需要额外建立 GitHub 仓库存放评论数据我为了维护成本再低一点最后把评论方案改成了类似留言板加社交媒体引流的组合文章底部引导读者去相应平台交流这样既保留了互动入口又不额外增加服务器依赖。说这些不是否定第三方评论方案而是要强调一个问题任何引入外部的功能都要预估它的可用性、维护成本和用户使用门槛。评论区看起来是个小功能真失败一次你就知道这其中的时间成本有多高了。5. 让博客更好用性能优化与内容维护心得5.1 基础性能优化三板斧博客的性能优化我先交个底静态站点的底线分本来就很高不需要做太多激进优化就能获得不错的体验但有三板斧一定要做扎实。第一板斧是开启全站 HTTPS 和 HTTP/2Cloudflare Pages 默认就是全站 HTTPSHTTP/2 也是默认开启的这两项几乎不用花心思。第二板斧是图片格式的现代化Cloudflare 在开启静态资源优化之后会自动把支持的浏览器请求定向到 WebP 格式体积相比 JPEG 可以再下降三成左右这同样是不需要额外配置就能获得的效果。第三板斧是自己动手做资源压缩这也是我实际收益最明显的动作。Hugo 构建的时候用--minify参数能自动压缩生成的 HTML 文件但 CSS 和 JS 有没有压缩取决于主题本身。主题如果没有自动压缩你可以用 Hugo 内置的resources.Minify函数在模板里手动压缩静态资源这需要改动一下主题模板。我改过一次之后页面原始大小从 60KB 降到了 15KB 左右加载速度肉眼可见地变快文章里嵌图片的页面改善更明显。做性能优化的过程中一定要避免过度设计的冲动。我看过一些朋友在博客里加了 Service Worker 做到完全离线可访问加了各种异步加载、骨架屏效果这些技术的演示价值远大于实际收益。个人博客的内容大多数是文本加少量图片把资源压缩好、缓存策略做对日常体验已经非常顺滑。把精力花在多余的前端性能优化上不如去写几篇高质量的文章。5.2 内容维护与持续写作的经验再好的技术架构也只是基础设施博客的价值归根到底在内容。我见过不少搭建时兴致勃勃的人博客上就三五篇文章之后就再也没有更新过。我自己的体会是持续写作靠的不是兴趣和冲动而是把写作成本压缩到足够低之后培养出来的习惯固定动作。现在我写一篇博客的完整流程是平时在手机备忘录里记录素材和灵感周末抽一整块时间先把思路整理成大纲然后打开编辑器照着大纲写初稿写完之后用语法检查和预览功能做一遍校对最后设置好标签和摘要推到 GitHub十分钟之后线上就已经更新完成。整个过程完全不用进入任何维护后台也没有数据库备份之类的事情要操心。内容规划上我会根据统计数据做动态调整看哪种主题的文章阅读量更高、读者互动更多然后适量增加相关内容。这里还有一个小技巧就是定期检查旧文章的链接是否有效尤其是引用了外部链接的文章很多外部资源时间一长就会失效定期清理和修正既能保证读者体验也有利于搜索引擎对站点质量的评价。5.3 几个容易被忽视的维护细节维护细节决定了博客能走多远。域名续费提醒这个事听起来很基础但我见过不止一个博客因为忘记续费而被他人抢注的情况。建议在手机日历上设置提前一个月的续费提醒同时开启自动续费功能规避掉这个低级但致命的失误。代码仓库的备份策略我也调整过一次之前只把博客源文件放在一个 GitHub 仓库里后来想万一账号出现异常整个博客可能就没了。现在我除了 GitHub 之外还会定期把整个目录打包加密之后上传到另一家云存储服务做到异地双备份。文章不多的时候备份操作不频繁每个月或者每十篇文章做一次就够了。还有一个细节是关于时间显示和写作日期管理的。Hugo 默认用 UTC 时间显示文章发布日期如果你是东八区会发现文章会显示成前一天的日期。解决方案是在配置文件的params里添加时区偏移参数或者在系统环境变量里设置TZAsia/Shanghai确保构建容器和本地环境使用相同的时区处理逻辑否则你晚上发的文章第二天早上看发布日期却是上一日。我在实际运营博客这段时间里最大的体会就是技术永远是服务表达的工具而不应该反过来绑架写作。静态博客这个方案让我把全部的精力都聚焦在内容本身需要还债的时间几乎没有。如果你也想搭建自己的博客希望这篇记录能给你省下一些选型对比的精力早日把时间投入到真正有价值的写作中去。