little-cat

前言

在这篇文章中，我将介绍如何使用 Cloudflare Pages 和 Hugo 框架搭建一个免费的静态博客。这个方案的优点包括：

  • 完全免费的托管服务
  • 自动化的部署流程
  • 全球 CDN 加速
  • 自定义域名支持
  • 简单易用的管理界面

准备工作

在开始之前，你需要准备：

  1. 一个 GitHub 账号 (https://github.com/)
  2. 一个 Cloudflare 账号 (https://www.cloudflare-cn.com/)
  3. Hugo 静态网站生成器（可选，用于本地预览）(https://themes.gohugo.io/)
  4. Git 基础知识

步骤一：创建 Hugo 网站

  1. 安装 Hugo（以 OSX 为例）：
1

brew install hugo
  1. 创建新的 Hugo 网站：
1
2

hugo new site my-blog
cd my-blog
  1. 初始化 Git 仓库：
1

git init
  1. 添加主题（以 PaperMod 为例）：

Hugo 提供了丰富的主题选择，你可以在官方主题网站 themes.gohugo.io 浏览和选择喜欢的主题。每个主题都有详细的文档和示例。以下是一些流行的主题：

  • PaperMod: 简洁现代的博客主题
  • LoveIt: 优雅的博客和文档主题
  • Stack: 功能丰富的卡片式主题
  • DoIt: 专注于文档和博客的主题

本教程使用 PaperMod 主题作为示例。安装主题：

1
2
3
4
5

# 添加主题作为git子模块
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

# 或者直接克隆主题
git clone https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

选择主题时的注意事项：

  1. 确认主题的更新维护状态

  2. 查看主题的文档和配置选项

  3. 检查主题的响应式设计

  4. 考虑是否支持多语言

  5. 评估主题的自定义难度

  6. 配置网站，编辑 hugo.toml：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

baseURL = 'https://your-domain.com/'
languageCode = 'zh-cn'
title = 'My Blog'  # 全局网站标题
theme = "PaperMod"

# 主题配置
[params]
  title = "My Blog"  # 主题显示标题
  description = "Welcome to my blog"
  # 其他配置...

配置文件说明

Hugo 的配置文件中有几个重要的标题相关配置：

  1. 全局标题配置

    1

    title = "网站标题"  # 根级别的标题
    • 作为整个网站的默认标题
    • 显示在浏览器的标签页上
    • 用作网站的品牌名称
    • 可以被页面级别的标题覆盖

  2. 主题参数中的标题

    1
2

    [params]
  title = "显示标题"  # 主题参数中的标题
    • 由主题模板决定显示位置
    • 通常用于网站 header 部分
    • 可以与全局标题不同
    • 支持更丰富的样式处理

  3. 语言特定的标题（多语言网站）

    1
2

    [languages.zh-cn]
  title = "中文标题"  # 特定语言的标题
    • 在对应语言环境下显示
    • 覆盖全局标题设置
    • 用于多语言网站定制

选择标题显示的建议：

  1. 如果网站是单语言的，可以让两个标题保持一致
  2. 如果需要在不同位置显示不同的标题，可以分别设置
  3. 具体的显示效果要参考所使用主题的文档说明

本地预览

Hugo 提供了强大的本地预览功能，你可以实时查看网站效果并进行调试。

基本预览命令

  1. 启动本地服务器：
1

hugo server

这个命令会启动一个本地服务器，默认地址是 http://localhost:1313

  1. 预览草稿内容：
1

hugo server -D

这个命令会同时显示标记为草稿的文章

  1. 实时预览：
1

hugo server --disableFastRender

这个命令会禁用快速渲染，确保看到的是最终效果

高级预览选项

  1. 指定端口：
1

hugo server -p 8080

如果默认的 1313 端口被占用，可以指定其他端口

  1. 允许局域网访问：
1

hugo server --bind 0.0.0.0

这样局域网内的其他设备也能访问预览

  1. 生产环境模拟：
1

hugo server --environment production

模拟生产环境的配置和行为

  1. 完整调试模式：
1

hugo server -D --disableFastRender --debug

显示详细的调试信息，适合排查问题

预览注意事项

  1. 实时更新

    • Hugo 会自动检测文件变化
    • 保存文件后浏览器会自动刷新
    • 无需手动重启服务器

  2. 缓存处理

    • 如果看到的不是最新内容，可以：
    • 清除浏览器缓存
    • 使用 hugo server --noHTTPCache
    • 强制刷新页面（Ctrl+F5 或 Cmd+Shift+R）

  3. 性能调优

    • 观察命令行输出的构建时间
    • 如果构建较慢，可以使用 hugo server --renderToDisk=false
    • 大型站点可以使用 hugo server --renderStaticToDisk

步骤二：创建 GitHub 仓库

  1. 在 GitHub 上创建新仓库
  2. 将本地代码推送到 GitHub：
1
2
3
4

git add .
git commit -m "Initial commit"
git remote add origin https://github.com/username/repo-name.git
git push -u origin main

步骤三：配置 Cloudflare Pages

  1. 登录 Cloudflare 控制台
  2. 进入 Pages 页面
  3. 点击"创建项目"
  4. 选择"连接到 Git"
  5. 选择你的 GitHub 仓库
  6. 配置构建设置：
    • 构建命令：hugo --gc --minify
    • 构建输出目录：public
    • 环境变量：
      • HUGO_VERSION: 0.123.0（或你使用的版本）

步骤四：自定义域名（可选）

  1. 在 Cloudflare Pages 项目设置中添加自定义域名
  2. 按照提示配置 DNS 记录
  3. 等待 SSL 证书自动配置完成

步骤五：编写和发布内容

  1. 创建新文章：
1

hugo new posts/my-first-post.md
  1. 编辑文章内容（使用 Markdown 格式）
  2. 提交并推送到 GitHub：
1
2
3

git add .
git commit -m "Add new post"
git push

Cloudflare Pages 会自动检测到更改并开始构建和部署。

维护和优化

1. 性能优化

  • 使用适当大小的图片
  • 启用 Hugo 的内容压缩
  • 利用 Cloudflare 的缓存功能

2. 安全性

  • 启用 Cloudflare 的安全功能
  • 定期更新 Hugo 和主题
  • 使用强密码和双因素认证

3. 备份

  • 定期备份 GitHub 仓库
  • 保存本地副本
  • 导出重要配置

常见问题

  1. 部署失败

    • 检查 Hugo 版本配置
    • 查看构建日志
    • 确认配置文件格式正确

  2. 图片无法显示

    • 检查图片路径
    • 确认图片已提交到仓库
    • 验证图片格式支持

  3. 自定义域名问题

    • 确认 DNS 记录配置正确
    • 等待 DNS 生效（可能需要 24-48 小时）
    • 检查 SSL 证书状态

结语

使用 Cloudflare Pages 部署 Hugo 静态博客是一个简单且免费的解决方案。它不仅提供了强大的性能和安全性，还能让你专注于内容创作。随着不断的实践，你会发现这个方案非常适合个人博客的搭建和维护。

如果你在搭建过程中遇到任何问题，欢迎在评论区留言讨论。