从零搭建个人技术博客：Hugo + GitHub Pages 实战指南

1. 为什么我劝你先想清楚“博客定位”再去碰任何工具很多朋友问过我怎么从零搭建个人技术博客大部分人的第一反应是去搜“最好用的博客框架”然后在 WordPress、Hexo、Hugo、VuePress 这几个名字之间反复横跳一连折腾好几天最后连一篇文章都没发出去。我的建议恰恰相反先别急着选工具先把“为什么要搭博客”这个问题想明白。个人技术博客的本质不是给搜索引擎看的门面也不是简历上的一行链接而是一个长期累积的、完全由自己掌控的知识资产。你在平台写作内容、流量、展示逻辑全都由平台决定你搭自己的博客数据、样式、发布节奏都握在自己手里。更重要的是博客写作是一个低成本的高强度学习闭环为了写清楚一个知识点你往往要查资料、做对比、复现实验这个过程的收获比单纯“看会了”要扎实得多。根据我这几年帮人搭博客、自己也重构过两次的经验可以把需求用户大致分成三类对应的选择完全不同只在本地记笔记偶尔想发出来分享这类人适合先跑通最简单的方案不需要一开始就上全套自动化部署能写、能发、能改就够。打算长期公开输出把博客当个人品牌经营这类人要重视站点速度、SEO、自定义域名、数据备份和写作体验静态站点生成器加免费托管是性价比最高的组合。需要完整后台管理喜欢可视化写文章这类人可能更适合 WordPress 之类带后台的解决方案但相应地要接受服务器成本和维护负担。我的建议是如果你是技术背景哪怕只是会一点 Git 和命令行都优先考虑静态站点方案。原因很现实——静态站点的最大优势不是“极客范儿”而是十年后它大概率还在。不需要续费服务器、不需要打安全补丁、不会被后台漏洞拖垮只需要一堆纯文本文件随便换一台电脑都能继续更新。2. 方案选型静态站点为什么成了最优解以及我在用的组合2.1 主流方案的取舍对比先说结论技术博客这事不存在“最好的方案”只存在“五年后你还在更新”的方案。我见过太多人第一年搞 WordPress花三天配服务器、装插件、调主题第二年续费时就嫌贵嫌麻烦弃坑了。所以选型的核心指标不是“功能最强”而是“维护成本最低”。我做过一轮实测对比整理成表格供你参考方案发布方式动态后台维护成本适合人群WordPress 云服务器后台发文章有高需续费、打补丁、防攻击喜欢可视化写作、愿意付费Hexo / Hugo / VuePress 静态站点写 Markdown部署到托管平台无极低几乎零费用愿意用 Git 和命令行的技术人语雀 / Notion 公开链接平台内发布有低但迁移受限只求快速分享的人自建平台账号公众号、知乎等平台内发布无低但受平台约束追求流量、不在乎数据私有静态站点生成器里Hexo 起步早、中文资料多但依赖 Node.js 生态装插件多了以后升级容易出一堆兼容问题。VuePress 本身是给项目文档设计的拿来写个人博客也能用但插件和主题要自己攒。我最后推荐的其实是 Hugo它是用 Go 写的只有一个可执行文件装完就能跑生成几百篇文章只需要几秒钟而且主题市场里专门针对博客的漂亮主题非常多。2.2 我的最终组合Hugo GitHub Pages 自定义域名我现在的博客架构非常简单拆开来看就三层内容层本地的 Markdown 源文件存在 Git 仓库里这是唯一需要长期维护的东西。生成层Hugo 把 Markdown 渲染成纯静态的 HTML/CSS/JS生成结果就是一个完整的网站文件夹。托管层推送到 GitHub 仓库由 GitHub Pages 免费托管再套上自己的域名。这个组合最大的好处是每一层都可以单独替换。比如哪天我不想用 GitHub Pages 了可以把 public 目录传到任意静态托管平台哪天我想换主题改一下 config 文件重新生成就行。数据和展示完全分离不会被任何服务商绑架。2.3 选型时很多人忽略的隐性成本这里我要认真提醒几个容易忽略的成本全是踩过坑才明白的第一是图床成本。很多人搭博客时只考虑文字发布几篇文章后才发现图片放在哪里是个大问题。如果你把图片直接放在文章目录里GitHub 仓库很快会变得臃肿如果用第三方图床免费的可能失效收费的又是一笔持续性支出。我的方案是先把图片放在站点的 static 目录里走同一套 Git 流程管理等以后图片量大了再考虑企业级对象存储。第二是维护精力的“衰减曲线”。动态方案的问题在于三个月不登录后台可能已经积了二十个安全更新等着你静态方案没有这个问题半年不管它也不会坏。从长期主义的角度看选静态方案就是在给自己留余地。第三是写作环境的迁移成本。用静态方案你的全部家当就是那个 Markdown 文件夹换电脑只需要克隆一下仓库用带后台的方案文章都锁在数据库里光导出就够折腾一小时。我身边真有朋友因为迁移太麻烦干脆放弃旧博客重开新号的这种损失比想象中大得多。3. 从零初始化域名、仓库和第一篇文章的实操记录3.1 域名注册与 DNS 解析的流程域名是博客的脸面我的建议是注册一个“个人品牌型”域名用自己名字的拼音或常用昵称即可后缀选 .com、.me、.dev 都行年费一般在几十到一百元以内。注册平台选大厂就好比如阿里云、腾讯云或国外注册商账号安全开启两步验证。实际操作中域名买完先不用急着解析因为 GitHub Pages 还没创建好指向了也没用。顺序应该是先在 GitHub 建仓库再配置域名最后解析。国内服务器建站需要完成备案流程但如果你像我一样直接用 GitHub Pages 托管这一步就可以省掉。说实话对个人博客来说这算一个实打实的便利。3.2 安装 Hugo 并创建第一个站点Hugo 的安装非常简单macOS 用户可以直接用 Homebrewbrew install hugoWindows 用户用包管理器或者直接下载可执行文件都行。装完验证一下版本hugo version然后创建一个新站点hugo new site myblog cd myblog这里有个容易踩的坑Hugo 新站点的目录结构是固定的包括 content、layouts、static、config 等文件夹。不要自己乱建文件先跑通默认流程再慢慢改造。很多新手一上来就想着改配置结果把目录结构搞乱了hugo server 直接报错。3.3 主题配置以 PaperMod 为例Hugo 默认不带主题你需要从主题市场挑一个。我目前用的是 PaperMod它非常契合技术博客的场景支持明暗模式、目录大纲、标签归档、搜索界面干净没有多余装饰。安装主题的方式是 Git 克隆git init git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod然后在 config.toml 里做基本配置baseURL https://yourdomain.com/ languageCode zh-cn title 你的博客名 theme PaperMod [params] ShowReadingTime true ShowShareButtons false ShowToc true description 记录技术与思考配完之后跑一下hugo server -D浏览器访问http://localhost:1313就能看到站点了。我强烈建议你现在就在本地跑通这一步因为看到本地站点能跑起来你才会有信心继续往下走这个心理正反馈比任何教程都有用。3.4 创建第一篇文章并理解 Hugo 目录逻辑创建第一篇文章用下面的命令hugo new posts/my-first-post.mdHugo 会在 content/posts 目录下生成带 Front Matter 的 Markdown 文件。Front Matter 是文件开头用包裹的元数据包括标题、日期、标签、是否草稿等字段。你只需要在正文区域写内容Hugo 构建时会自动套用主题模板渲染成 HTML。第一篇文章随便写什么关键在于把这个流程跑完整写、预览、生成、部署。很多人的博客“难产”不是能力问题而是从来没有完整地走通过一次发布链路。先发一篇测试文章相当于给整个系统做了一次冒烟测试。4. 自动部署让每一次 Git 提交自动变成线上更新4.1 为什么必须上自动化部署如果你每次更新博客都要手动执行hugo生成 public 目录、再手动上传到托管空间那大一两次可以坚持一年下来绝对会烦。自动化部署的意义不是“酷”而是把发布成本降到零——你只需要git push一条命令线上站点几秒内自动更新这才是你愿意长期写下去的前提。我用的方案是 GitHub Actions。它在每次代码推送时自动执行安装 Hugo、生成静态文件、推送到发布分支。4.2 一步一步配置工作流文件完整的 workflow 文件放在.github/workflows/deploy.yml内容可以参考下面的配置name: deploy on: push: branches: [main] jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 with: submodules: recursive - name: Setup Hugo uses: peaceiris/actions-hugov3 with: hugo-version: 0.125.0 - name: Build run: hugo --minify - name: Deploy uses: peaceiris/actions-gh-pagesv4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./public这里有三点需要说明actions-hugo可以指定 Hugo 版本避免本地版本和线上版本不一致导致渲染结果不同。actions-gh-pages会把构建结果推送到仓库的gh-pages分支GitHub Pages 从那个分支读取站点。仓库的 Pages 设置里Source 要选Deploy from a branch分支选gh-pages。第一次部署完你访问https://你的用户名.github.io/仓库名/应该能看到站点。这里有个小认知要提前纠正很多人以为 GitHub Pages 的访问地址一定是用户名.github.io其实如果你把仓库命名为用户名.github.io首页就是根地址用其他仓库名则会有子路径所以建议博客仓库直接命名为用户名.github.io这样路径最干净。4.3 自定义域名与 HTTPS 强制跳转站点跑通后进入仓库的 Settings → Pages在 Custom domain 栏填入你购买的域名保存。接着回到域名服务商后台添加解析记录类型 CNAME主机记录填www或记录值填用户名.github.io类型 A记录值填 GitHub Pages 的 IP 地址段80、82、192.0.2.1 这类专用于 Pages 的地址以官方文档为准DNS 解析生效通常需要几分钟到几小时不等解析完成后回到 GitHub Pages 设置里勾选 Enforce HTTPS让所有访问强制跳转到 HTTPS。这一步别省否则访问地址里的锁标志会提示不安全观感很差。我在实操中发现很多人在这里会被www和的解析方式绕晕。最简单稳妥的做法是给两个都加上 CNAME 记录指向同一个地址然后在仓库根目录放一个 CNAME 文件内容写你的主域名。这样用户无论输不输www都能访问而且不会被浏览器识别为跨域。5. 写作体验优化让写文章这件事舒舒服服坚持三十年5.1 建立一套文章模板和工作流博客能否持续更新拼的不是意志力而是流程是否流畅。如果每次写文章都要从空白页面开始、纠结格式、处理图片、调排版那写五篇之后热情就没了。我的做法是先定义好一套标准模板每次新建文章直接套用。在 Hugo 里你可以在archetypes/posts.md里定义默认模板--- title: {{ .Name }} date: {{ .Date }} draft: true tags: [] categories: [] description: --- ## 背景 ## 问题 ## 分析 ## 结论这样每次敲hugo new posts/新文章.md自动生成带四个章节骨架的文件。你只需要往里填内容不用从零开始组织结构。标题、标签、描述在写之前就填好发布前再检查一遍。5.2 图片策略不要让图床焦虑毁掉你的写作图片处理是最容易让新手崩溃的环节。你可能会看到网上各种图床教程什么对象存储、CDN、防盗链对个人博客来说完全是杀鸡用牛刀。我的建议是初期直接把图片放在static/images目录下文章里用相对路径引用。这样做有几个好处图片和文章一起走 Git 流程永远不会出现图床过期导致图片丢失的情况。不需要额外注册账号、配置密钥、计算带宽费。仓库结构一目了然备份就是克隆一次代码。等以后图片累计超过几百张再考虑切换到对象存储加 CDN 不迟。对一个技术博客来说图片量级要撑爆 GitHub 仓库存储限制1GB你得日更超过五年才做得到这个迁移完全可以等到真有必要时再做。5.3 本地写作工具链从编辑器到预览Markdown 编辑器我推荐直接用 VS Code 或者任何你熟悉的编辑器加 Markdown 插件不用为了写博客专门换工具。关键是掌握几个提高效率的快捷键和习惯打开多个相关文件用分栏一边写正文一边查参考资料。写完标题层级再润色正文先尽量流畅地倒出来不要边写边改。本地跑hugo server -D利用浏览器实时预览每写几段就扫一眼排版。另外一个提高效率的技巧是维护一个“素材草稿箱”。我平时看到好的想法、踩了一个值得记录的坑第一时间丢进一个drafts目录每次新建博客系统会把它列出来。写文章时大部分时间是整理这些素材而不是从空白页开始冥思苦想。“先收集再成文”是保持更新频率最有效的工作习惯。6. 发布、收录与长期维护从搭好到真正用起来的最后一公里6.1 发布前必须检查的五件事我在博客上发文章发多了以后总结出一个发布前检查清单每次发文章前花两分钟过一遍能避免九成以上的返工文章标题是否准确传达内容是否包含了目标读者会搜索的关键词。Front Matter 里的 tags、categories 是否正确这直接影响站点内的归档和推荐。Markdown 排版是否有四级以上标题混乱的情况代码块是否标注了语言。文章里的图片、链接是否都能正常访问尤其是相对路径别写错。描述字段 description 是否言之有物别随便填个“个人博客文章”这个字段是搜索引擎展示摘要和分享卡片时的重要信息。6.2 被搜索引擎收录Sitemap 与站点验证不少人搭完博客发了几篇文章然后在搜索里怎么也找不到自己的站点以为是哪里没配对。其实搜索引擎收录是需要主动“敲门”的Hugo 本身会自动生成 sitemap.xml你要做的是告诉搜索引擎这个文件存在。我建议按这个顺序操作确认访问https://你的域名/sitemap.xml能正常打开。到 Google Search Console 添加你的域名用 HTML 文件或 DNS 记录完成验证。提交站点地图也就是那串 sitemap.xml 的地址。用“网址检查”工具主动提交一篇文章的 URL让搜索引擎快速抓取。这个过程一周内通常能看到效果新站点的收录速度不如大站快不用焦虑。坚持更新慢慢积累“站点权重”才是个人博客在搜索引擎立足的正道。6.3 数据备份把博客当资产而不是玩具静态博客有个看起来很“安全”的误区既然文章都在 Git 仓库里那就不用备份了。实际上如果你只有一个远程仓库遇到账号被盗、仓库被删、误操作强制推送等情况照样可能丢失文章。我的备份策略非常简单仓库本身是一份远程备份。本地电脑上是另一份完整副本。每隔一段时间我习惯一个月把整个 content 目录打包加密后传到独立网盘或移动硬盘。三步加在一起成本几乎为零却能保证最坏情况下你的写作成果不丢。“博客是资产”这个认知一旦建立备份就不是任务而是习惯。6.4 关于长期更新的几句实话写博客这件事最难的永远是开始之后没有立刻见效的那段时间。你可能前三个月访客只有个位数搜索引擎不收录评论区空荡荡这时候最容易放弃。我的真实体会是个人技术博客的核心收益是三五年尺度上缓慢浮现的。它会在你需要时成为一张可靠的“名片”会在你面试时成为最有说服力的作品集会在你写复杂问题排查时帮你回忆起半年前踩过的坑。这些东西都不是开通博客第一个月就能体会到的但是只要你不删站、不弃更它们就一直在那里累积。所以如果你问我从零搭建个人技术博客最重要的是什么我的答案不是选什么框架、用什么托管、配什么域名而是把整个发布流程简化到“无法再简化”然后逼自己写下去。工具只是手段流水不争先争的是滔滔不绝。