一、为什么选这条路
写博客常见三种做法:WordPress 这类动态博客、Hexo/Hugo 这类静态博客、直接在平台上开号。我选静态博客,理由三条:
- 不要服务器:生成的是纯 HTML,托管在 GitHub Pages 上,免费。
- 不怕丢:文章是 Markdown,全在 Git 仓库里。
- 打开快:没有数据库和后台,访问的就是静态文件。
代价是:没有后台界面,写完要"推"一下才上线。
二、装 Hugo
Hugo 负责把 Markdown 变成网页,就一个可执行文件,不用配环境。
- Windows:
winget install Hugo.Hugo.Extended - macOS:
brew install hugo
敲 hugo version 看到版本号就成(要 0.146 以上)。
三、建站、装主题
hugo new site myblog
cd myblog
git init
主题我用 PaperMod:把它的文件放进 themes/PaperMod/。站点名、菜单、首页那句话、深浅色都写在 hugo.toml 里,主题自带的示例照着改就行。
四、写第一篇文章
hugo new content posts/hello.md
每篇开头有一小段 front matter:
---
title: "文章标题"
date: 2026-09-27
tags: ["随笔"]
draft: false
---
draft: true 是草稿,不会发出去。正文就是普通 Markdown:## 小标题、**加粗**、反引号包代码块。
本地预览:hugo server -D,浏览器开 http://localhost:1313 ,边写边看。
五、推到 GitHub、打开 Pages
建一个 public 仓库,把代码推上去:
git remote add origin https://github.com/<用户名>/<仓库名>.git
git branch -M main
git push -u origin main
然后到仓库 Settings → Pages,Source 选 GitHub Actions。
想做到"推送即上线",再加一个工作流 .github/workflows/hugo.yml:装 Hugo、hugo --minify、把产物发布到 Pages。配一次,以后只管写。
六、绑自己的域名
- 域名商那边加解析:
blog用 CNAME 指向<用户名>.github.io; - 仓库
static/CNAME文件里写你的域名(一行); - 回 Pages 设置填 Custom domain,证书签好再勾 Enforce HTTPS。
顺序别反:先改 DNS,再放 CNAME 文件,反了站点会跳到一个还没生效的域名,打不开。
七、评论
想要评论区用 Giscus:评论存在 GitHub Discussions 里,不需要数据库。把 Giscus 的 GitHub App 装到你的仓库,再在评论模板里填仓库、repo-id、category-id。App 不装,页面会报 giscus is not installed on this repository。
八、踩过的坑
- baseURL 写错:Pages 地址带仓库名,写错会导致 CSS 加载不出来,页面裸奔。
- 别改文章文件名:Giscus 按路径认讨论帖,改名旧评论就对不上了。
- 国内访问:GitHub Pages 在国外,速度看运气;想稳就备案后放自己的服务器,或套 CDN。
gh-pages分支别动:那是自动生成的产物。
最后一句实话:搭站只要一个下午,难的是把第一篇写完。