一、项目概述为什么选择 Hugo GitHub Pages对于技术博主来说最理想的写作体验是“用 Markdown 写作Git 管理版本一次推送自动上线”。而Hugo GitHub Pages GitHub Actions的组合恰好能完美实现这个流程。这套方案的核心优势非常突出优势说明完全免费GitHub Pages 提供免费托管 全球 CDN 加速无需购买服务器极致性能Hugo 是Go语言写的静态生成器构建速度毫秒级生成纯HTML页面访问极快高安全性没有数据库、没有服务端脚本从根本上杜绝了SQL注入等常见漏洞版本控制所有文章和配置都用 Git 管理历史变更清晰可查写作纯粹用 Markdown 写作专注于内容本身下面以开源项目cappuccino.github.io为参考一步步带你搭建属于自己的技术博客。二、技术选型参考这个项目的技术栈框架Hugo —— 全球最快的静态网站生成器主题Gokarna —— 极简风格专注于内容呈现托管GitHub Pages —— 永久免费自带SSL证书和CDN加速自动化部署GitHub Actions —— 推送代码后自动构建并发布你也可以选择其他主题如 PaperMod、Ananke 等Hugo 官方主题库有 2000 主题可供选择。三、详细搭建步骤第一步安装 HugoMac使用 HomebrewbrewinstallhugoWindows使用 Scoopscoopinstallhugo-extendedLinux直接下载二进制从 Hugo Releases 下载对应版本解压后放到/usr/local/bin/。安装完成后验证hugo version第二步创建 Hugo 站点# 创建新站点将 myblog 替换为你的博客名称hugo new site myblogcdmyblog# 初始化 Git 仓库gitinit第三步安装主题以 Gokarna 主题为例# 将主题添加为 Git 子模块方便后续更新gitsubmoduleaddhttps://github.com/gokarna-theme/gokarna-hugo themes/gokarna在hugo.toml或hugo.yaml中配置主题theme gokarna baseURL https://你的用户名.github.io/ title 你的博客名称 languageCode zh-CN第四步撰写第一篇文章在content/posts/目录下创建 Markdown 文件hugo new posts/第一篇文章.md打开文件在顶部添加 Front Matter 元数据---title:第一篇文章date:2026-06-27draft:falsetags:[Hugo,博客]---这里是文章正文使用 Markdown 语法写作...注意draft: true的文章在构建时不会被发布写完后记得改为false。第五步本地预览hugo server-D打开浏览器访问http://localhost:1313即可实时预览效果。修改内容后页面会自动刷新。四、部署到 GitHub Pages4.1 创建 GitHub 仓库登录 GitHub点击右上角→New repository仓库名设置为你的用户名.github.io例如kabuqin.github.io选择Public不要勾选初始化 README4.2 关联本地仓库并推送gitremoteaddorigin https://github.com/你的用户名/你的用户名.github.io.gitgitadd.gitcommit-m初始化博客gitpush-uorigin main五、配置 GitHub Actions 自动部署这是整个流程中最关键的一步——实现“推送即部署”。5.1 创建 GitHub Actions 工作流在项目根目录创建.github/workflows/deploy.ymlname:Build and Deployon:push:branches:-main# 当推送到 main 分支时触发workflow_dispatch:# 支持手动触发permissions:contents:readpages:writeid-token:writeconcurrency:group:pagescancel-in-progress:falsejobs:build:runs-on:ubuntu-lateststeps:-name:Checkoutuses:actions/checkoutv4with:submodules:recursive# 拉取主题子模块fetch-depth:0-name:Setup Hugouses:peaceiris/actions-hugov3with:hugo-version:0.119.0extended:true-name:Buildrun:hugo--minify# 生成静态文件到 public/ 目录-name:Upload artifactuses:actions/upload-pages-artifactv3with:path:./publicdeploy:environment:name:github-pagesurl:${{steps.deployment.outputs.page_url}}runs-on:ubuntu-latestneeds:buildsteps:-name:Deploy to GitHub Pagesid:deploymentuses:actions/deploy-pagesv4这个工作流会自动完成拉取代码包括主题子模块安装 Hugo执行hugo --minify构建静态文件将生成的public/目录部署到 GitHub Pages5.2 启用 GitHub Pages进入仓库 →Settings→Pages在Source处选择GitHub Actions配置完成无需保存按钮更改即时生效5.3 推送触发部署gitadd.gitcommit-m添加自动部署配置gitpush推送后前往仓库的Actions选项卡查看部署进度。绿色对勾表示部署成功。访问https://你的用户名.github.io/即可看到你的博客。六、日常写作流程博客搭建完成后日常写作只需三步新建文章hugo new posts/文章标题.md写作用 Markdown 编写内容修改 Front Matter 中的draft: false发布git add . git commit -m 新增文章 git push推送后 GitHub Actions 自动构建部署几分钟后线上更新。七、目录结构说明参考项目的目录结构myblog/ ├── content/ │ └── posts/ # 所有博客文章Markdown ├── static/ # 静态资源图片、CSS等 ├── themes/ # 主题通过 Git submodule 管理 ├── hugo.toml # Hugo 配置文件 ├── .github/ │ └── workflows/ │ └── deploy.yml # GitHub Actions 自动部署配置 └── public/ # 构建生成的静态文件自动生成不提交八、进阶优化建议自定义域名在static/目录下创建CNAME文件写入你的域名图片优化使用 ImageOptim 等工具压缩图片添加懒加载SEO 优化在hugo.toml中配置enableRobotsTXT true统计分析接入 Google Analytics 或 Umami 等免费工具总结通过Hugo GitHub Pages GitHub Actions这套方案你可以零成本搭建一个高性能、高安全性的技术博客。整个流程的核心是“内容即代码”——用 Markdown 写作用 Git 管理推送即自动部署。就像 cappuccino.github.io 这个项目一样你只需要专注于写出优质的技术文章剩下的构建和部署工作全部交给自动化流程去完成。