从零搭博客：Hugo + GitHub + Cloudflare Pages

花了大半天时间，把个人博客搭起来了。技术栈是 Hugo + GitHub + Cloudflare Pages，全程免费，不需要买服务器。整个过程记录一下，方便以后回看，也给想搭博客的人做个参考。

为什么选这套方案

之前考虑过 Hexo、VuePress，也想过直接用 WordPress。最后选 Hugo 是因为：

生成速度极快，本地秒级构建
主题生态成熟，PaperMod 颜值在线
纯静态，不需要后端服务器
Cloudflare Pages 免费托管，自带全球 CDN

部署流程：本地写 Markdown → git push → Cloudflare 自动构建 → 站点上线。比写代码还快。

环境准备

机器上需要装两个东西：

Git（代码版本管理）
Hugo（Extended 版本，主题会用到 SCSS）

我的环境是 Windows + Git Bash，Hugo 直接从 GitHub Release 下载解压即可。如果你也走这条路，建议下载 Extended 版，否则换主题时可能报 SCSS 编译错误。

创建项目

Hugo 创建项目的命令很简单：

1
2
3
hugo new site myblog
cd myblog
git init

但我这里走了另一条路——因为网络原因下载主题很慢，直接自己写了一套极简的 HTML/CSS 模板放在 layouts/ 目录下。先让站点能跑起来，后续再换主题。这个思路适合想快速看到效果的人：先上线，再迭代。

目录结构大概是：

1
2
3
4
5
6
7
8
9
myblog/
├── archetypes/          # 文章模板
├── content/             # 所有文章
│   ├── posts/
│   └── about.md
├── layouts/             # HTML 模板（初始用自定义，后来换 PaperMod）
├── static/css/          # 样式
├── hugo.toml            # 站点配置
└── .github/workflows/   # 自动部署（后来弃用了）

推送到 GitHub

在 GitHub 新建一个仓库，仓库名随意，我用的 myblog。然后本地推送：

1
2
3
4
5
git remote add origin https://github.com/maige12138/myblog.git
git branch -M main
git add -A
git commit -m "init: Hugo blog"
git push -u origin main

这里注意：初始配置里 hugo.toml 的 baseURL 先填 Cloudflare Pages 的域名，不然后期所有链接都指向本地或 GitHub Pages 地址，导致资源加载失败。

部署到 Cloudflare Pages

这是最关键的一步。操作顺序：

登录 Cloudflare Dashboard
左侧菜单选 Pages → Create a project
连接 GitHub 仓库，选 maige12138/myblog
填写构建设置：
- Build command: hugo --minify
- Build output directory: public
环境变量添加 HUGO_VERSION = 0.147.9
点击 Save and Deploy

等几分钟，Cloudflare 会分配一个 *.pages.dev 域名，比如我的 myblog-3p3.pages.dev。以后每次 git push，Cloudflare 都会自动重新构建，完全不用手动干预。

踩坑记录

搭建过程中踩了几个坑，这里列一下：

1. GitHub Actions 构建失败

仓库里放了一个 .github/workflows/hugo.yml，目的是用 GitHub Pages 自动部署。但因为没有在仓库设置里开启 Pages，导致每次 push 都报 ❌。

解决：既然用 Cloudflare Pages，GitHub Actions 完全不需要。直接删除 .github 文件夹，推送后就不会再报错了。

2. `theme = ""` 导致构建失败

最初 hugo.toml 里写了 theme = ''，Hugo 把它当作空模块去 themes/ 目录查找，结果报错 module "" not found。

解决：使用内置主题（模板在 layouts/ 目录）时，直接删掉 theme 字段，不要留空字符串。

3. `socialIcons` TOML 语法错误

配置 PaperMod 的社交链接时，写了：

1
2
[params.socialIcons]
  [[params.socialIcons]]

TOML 里 [params.socialIcons] 定义了一个表，紧接着 [[params.socialIcons]] 试图定义数组，两者冲突。

解决：只保留 [[params.socialIcons]] 数组形式，删掉前面的 [params.socialIcons] 表定义。

4. 首页第一篇文章样式特殊

PaperMod 默认会让首页第一篇文章使用 first-entry 样式（更大更突出），而 /posts/ 页面下的文章是 post-entry 卡片样式，两者不一致。

解决：在 hugo.toml 中设置 disableSpecial1stPost = true，首页所有文章统一使用卡片样式。

换主题：PaperMod

自带的主题太简陋，换成了 PaperMod。操作步骤：

1
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

然后删除旧的 layouts/ 和 static/css/ 文件，重写 hugo.toml 配置。PaperMod 的参数很多，我只挑了核心功能：

暗色/亮色自动切换
阅读时间、字数统计
代码复制按钮
目录导航（TOC）
导航栏头像 + GitHub/邮箱图标

还做了一处自定义：覆盖了 layouts/partials/header.html，在导航栏左侧增加了头像和社交图标，点击图标直接跳转 GitHub 和邮箱。

最终配置概览

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
baseURL = 'https://myblog-3p3.pages.dev'
languageCode = 'zh-CN'
title = '麦格要努力'
theme = 'PaperMod'

[params]
  defaultTheme = 'auto'
  disableSpecial1stPost = true
  ShowReadingTime = true
  ShowCodeCopyButtons = true
  
  [params.label]
    text = '麦格要努力'
    icon = 'https://github.com/maige12138.png'
  
  [[params.socialIcons]]
    name = 'github'
    url = 'https://github.com/maige12138'

后续写作流程

现在写博客已经很简单了：

在 content/posts/ 新建 .md 文件
写好内容，front matter 加上 draft: false
git add . && git commit -m "xxx" && git push origin main
等 1-2 分钟，Cloudflare 自动构建完成

不需要打开任何后台，不需要登录任何面板。git push 就是发布。

总结

整个搭建过程从 0 到上线，大概花了 2-3 小时。大部分时间花在踩坑和调主题上，实际搭建逻辑很清晰：

Hugo 生成静态文件 → Git 托管代码 → Cloudflare 自动构建部署

这套方案适合不想折腾服务器、不想花钱、只想安静写博客的人。推荐。

参考链接：

为什么选这套方案#

环境准备#

创建项目#

推送到 GitHub#

部署到 Cloudflare Pages#

踩坑记录#

1. GitHub Actions 构建失败#

2. theme = "" 导致构建失败#

3. socialIcons TOML 语法错误#

4. 首页第一篇文章样式特殊#

换主题：PaperMod#

最终配置概览#

后续写作流程#

总结#