# 2026 保姆级教程｜Github+Hugo+Cloudflare，零成本搭建个人技术博客



## 引言

在数字时代，拥有一个个人技术博客是展示技能、分享知识、建立个人品牌的绝佳方式。然而，许多人因为成本、技术门槛或维护复杂性而却步。本文将介绍一种 **零成本**、**高稳定性**、**易于维护** 的解决方案：使用 **GitHub** 托管代码、**Hugo** 生成静态网站、**Cloudflare Pages** 部署，并搭配功能强大的 **FixIt** 主题。

### 为什么选择这个技术栈？

- **GitHub**：免费私有仓库，版本控制，协同工作。
- **Hugo**：全球最快的静态网站生成器之一，使用 Go 语言编写，构建速度极快。
- **Cloudflare Pages**：全球 CDN 加速，免费 SSL 证书，自动构建和部署。
- **FixIt**：现代化的 Hugo 主题，功能丰富，性能优异，支持多语言、评论系统、SEO 优化等。

这套方案完全免费（个人使用），并且可以轻松扩展到生产环境。

### 适用场景

- **个人技术博客**：记录学习笔记、项目经验、技术心得。
- **作品集展示**：展示开发项目、设计作品、写作文章。
- **知识分享**：分享特定领域的知识，如编程、设计、数据分析。
- **团队文档**：小型团队或开源项目的文档站点。
- **实验性项目**：快速搭建和部署实验性网站。

无论你是学生、开发者、设计师还是技术爱好者，这个方案都能满足你的需求。

---

## 准备工作

### 所需工具

1. **Git**：版本控制工具。[下载地址](https://git-scm.com/)
2. **Hugo Extended**：静态网站生成器（Extended 版本支持 SCSS）。[安装指南](https://gohugo.io/installation/)
3. **文本编辑器**：推荐 VS Code、Sublime Text 或任何你喜欢的编辑器。
4. **终端**：命令行界面（Windows 可使用 PowerShell 或 WSL，macOS/Linux 使用 Terminal）。

### 账号注册

1. **GitHub 账号**：[注册地址](https://github.com/)
2. **Cloudflare 账号**：[注册地址](https://www.cloudflare.com/)（使用 GitHub 登录更便捷）

---

## 第一步：创建 GitHub 仓库

![创建GitHub仓库](/images/step1-create-repo.png)

### 1.1 新建仓库

登录 GitHub，点击右上角 "+" 按钮，选择 "New repository"。

- **Repository name**：建议使用 `my-blog` 或 `tech-blog`。
- **Description**：可选，例如 "我的个人技术博客"。
- **Public/Private**：选择 Public（免费）或 Private（Hugo 生成的静态文件可以托管在 Public 仓库）。
- **Initialize this repository with**：**不要**勾选任何初始化选项（如 README、.gitignore 等）。

点击 "Create repository"。

### 1.2 克隆仓库到本地

在终端中执行以下命令（将 `<your-username>` 和 `<repo-name>` 替换为你的信息）：

```bash
git clone https://github.com/<your-username>/<repo-name>.git
cd <repo-name>
```

### 1.3 初始化 Hugo 站点

在仓库目录中，执行：

```bash
hugo new site . --force
```

这会在当前目录创建 Hugo 站点结构。

---

## 第二步：安装和配置 Hugo 主题

### 2.1 选择 Hugo 主题

这里我们使用功能丰富的 **FixIt** 主题。有三种安装方式：

#### 方式一：使用 FixIt CLI（推荐）

```bash
npx fixit-cli create my-blog
```

#### 方式二：Git Submodules（传统方式）

```bash
git submodule add https://github.com/hugo-fixit/FixIt.git themes/FixIt
```

#### 方式三：Hugo Modules（高级方式）

1. 初始化 Hugo 模块：
   ```bash
   hugo mod init github.com/<your-username>/<repo-name>
   ```
2. 在 `hugo.toml` 中添加：
   ```toml
   [module]

   [[module.imports]]
   path = "github.com/hugo-fixit/FixIt"
   ```

### 2.2 配置主题

打开 `hugo.toml` 文件，添加以下基本配置：

```toml
baseURL = "https://<your-username>.github.io/<repo-name>/"
languageCode = "zh-cn"
title = "我的技术博客"
theme = "FixIt"

# 启用 Git 信息
enableGitInfo = true

# 默认主题：light / dark / auto
[params]
defaultTheme = "auto"

# 站点描述
description = "记录技术学习和项目经验的博客"

# 作者信息
[params.author]
name = "你的名字"
email = "your-email@example.com"
link = "https://github.com/<your-username>"
avatar = "/images/avatar.jpg"

# 搜索功能
[params.search]
enable = true
type = "fuse"

# 评论系统（以 Waline 为例）
[params.page.comment]
enable = true

[params.page.comment.waline]
enable = true
serverURL = "https://your-waline-server.vercel.app"

# 数学公式支持
[params.page.math]
enable = true
type = "katex"
```

### 2.3 创建第一篇文章

```bash
hugo new posts/my-first-post.md
```

编辑 `content/posts/my-first-post.md`：

```markdown
---
title: "我的第一篇文章"
date: 2026-03-29T20:00:00+08:00
draft: false
tags: ["Hugo", "博客", "教程"]
categories: ["技术"]
---

## 欢迎来到我的博客

这是我的第一篇文章，使用 Hugo 和 FixIt 主题生成。

### 功能展示

- 支持 **Markdown** 语法
- 支持代码高亮
- 支持数学公式：$E = mc^2$
- 支持图表（Mermaid）

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

感谢阅读！
```

---

## 第三步：本地预览和测试

### 3.1 启动开发服务器

```bash
hugo server -D
```

访问 `http://localhost:1313` 预览博客。

### 3.2 构建静态站点

测试构建命令：

```bash
hugo --minify
```

这会生成 `public` 目录，包含所有静态文件。

---

## 第四步：部署到 Cloudflare Pages

### 4.1 连接 GitHub 仓库

1. 登录 [Cloudflare Dashboard](https://dash.cloudflare.com/)。
2. 进入 "Workers & Pages"，点击 "Create application" -> "Pages" -> "Connect to Git"。
3. 选择你的 GitHub 仓库，授权 Cloudflare 访问。

### 4.2 配置构建设置

- **Project name**：项目名称（自动生成或自定义）。
- **Production branch**：`main` 或 `master`。
- **Build command**：`hugo --minify`（或者 `bash build.sh` 如果你有自定义脚本）。
- **Build output directory**：`public`（如果是 FixIt 主题的 demo 应用，可能是 `apps/demo/public`）。

### 4.3 环境变量（可选）

如果使用 Hugo Modules，可能需要设置环境变量：

- **HUGO_VERSION**：`0.156.0` 或更高版本。
- **HUGO_ENV**：`production`。

### 4.4 部署

点击 "Save and Deploy"。Cloudflare 会自动拉取代码、构建并部署。

几分钟后，你会获得一个 `*.pages.dev` 域名，例如：`https://my-blog.pages.dev`。

---

## 第五步：自定义域名（可选）

### 5.1 购买或使用已有域名

在域名注册商处购买域名，或使用已有的域名。

### 5.2 配置 DNS

在 Cloudflare DNS 设置中，添加一条 CNAME 记录：

- **Type**：CNAME
- **Name**：`www`（或 `@`）
- **Target**：`<your-project>.pages.dev`
- **Proxy status**：启用（橙色云朵）

### 5.3 在 Cloudflare Pages 绑定域名

1. 进入 Pages 项目设置 -> "Custom domains"。
2. 点击 "Set up a custom domain"，输入你的域名。
3. Cloudflare 会自动配置 SSL 证书。

---

## 进阶技巧

### 1. 使用 FixIt 主题的丰富功能

FixIt 主题提供了许多开箱即用的功能：

#### 评论系统

支持 Disqus、Gitalk、Waline、Twikoo 等多种评论系统。在 `hugo.toml` 中配置：

```toml
[params.page.comment.twikoo]
enable = true
envId = "https://your-twikoo-id"
```

#### 搜索功能

支持 Algolia、Fuse.js、Google CSE 等搜索后端：

```toml
[params.search]
enable = true
type = "algolia"
```

#### SEO 优化

主题内置了 SEO 优化，包括 JSON-LD 结构化数据、Open Graph、Twitter Cards 等。

### 2. 自定义主题样式

创建 `assets/css/_override.scss` 文件，覆盖主题变量：

```scss
// 全局字体
$global-font-family: 'LXGW WenKai', $global-font-family;

// 代码字体
$code-font-family: 'Fira Mono', $code-font-family;

// 页面宽度
[data-page-style='custom'] {
  %page-style {
    width: 80%;
    max-width: 1200px;
  }
}
```

### 3. 添加 Google Analytics

```toml
[params.analytics.google]
id = "G-XXXXXXXXXX"
anonymizeIP = true
```

### 4. 多语言支持

FixIt 支持 17 种语言。在 `hugo.toml` 中配置：

```toml
[languages]

[languages.en]
languageCode = "en"
title = "My Tech Blog"
weight = 1

[languages.zh-cn]
languageCode = "zh-cn"
title = "我的技术博客"
weight = 2
```

### 5. 使用 PWA（渐进式 Web 应用）

```toml
[params]
enablePWA = true
```

### 6. 自动部署工作流

在 GitHub 仓库中创建 `.github/workflows/deploy.yml`，实现推送代码后自动构建和部署。

---

## 常见问题解答

### Q1: Hugo Extended 版本是什么？为什么需要它？

A1: Hugo Extended 版本支持 SCSS/SASS 处理。FixIt 主题使用 SCSS 进行样式设计，因此需要 Extended 版本。

### Q2: 如何更新 FixIt 主题？

A2: 如果使用 Git Submodules：
```bash
git submodule update --remote --merge themes/FixIt
```

如果使用 Hugo Modules：
```bash
hugo mod get -u github.com/hugo-fixit/FixIt
```

### Q3: Cloudflare Pages 构建失败怎么办？

A3: 检查构建日志，常见问题：
- Hugo 版本过低：设置环境变量 `HUGO_VERSION=0.156.0`。
- 构建命令错误：确保命令正确，例如 `hugo --minify`。
- 输出目录错误：确认是 `public` 或 `apps/demo/public`。

### Q4: 如何添加图片？

A4: 在 `static/images/` 目录下添加图片，然后在 Markdown 中引用：
```markdown
![图片描述](/images/example.jpg)
```

### Q5: 如何启用 MathJax 或 KaTeX 数学公式？

A5: 在 `hugo.toml` 中配置：
```toml
[params.page.math]
enable = true
type = "katex" # 或 "mathjax"
```
然后在文章中使用 LaTeX 语法。

---

## 配图建议

为了让文章更直观，建议在以下步骤添加配图：

1. **GitHub 仓库创建**：截图展示创建仓库的界面。
2. **Hugo 站点结构**：展示 `hugo new site` 生成的目录结构。
3. **FixIt 主题预览**：展示主题的演示站点截图。
4. **本地预览**：展示 `hugo server` 后的浏览器界面。
5. **Cloudflare Pages 部署**：截图展示 Cloudflare Pages 的配置界面。
6. **最终效果**：展示部署后的博客首页、文章页、移动端适配等。

可以使用工具如 **ShareX**、**Flameshot**（Linux）、**截图工具**（Windows/macOS）来截取图片，并上传到图床（如 GitHub 仓库的 `images` 目录）。

---

## 总结

通过 GitHub + Hugo + Cloudflare Pages 的组合，你可以零成本搭建一个高性能、高可用的个人技术博客。FixIt 主题提供了丰富的功能和现代化的设计，让你专注于内容创作，而无需担心技术细节。

### 资源链接

- **FixIt 主题文档**：[https://fixit.lruihao.cn/documentation/](https://fixit.lruihao.cn/documentation/)
- **Hugo 官方文档**：[https://gohugo.io/documentation/](https://gohugo.io/documentation/)
- **Cloudflare Pages 文档**：[https://developers.cloudflare.com/pages/](https://developers.cloudflare.com/pages/)
- **GitHub 文档**：[https://docs.github.com/](https://docs.github.com/)

开始你的博客之旅吧！分享你的知识，记录你的成长。


---

> 作者: [小磊哥](https://github.com/Venice851007)  
> URL: /posts/2026-guide-github-hugo-cloudflare-blog/