Hugo + GitHub + Cloudflare Pages 个人博客搭建全流程指南

本指南整合了从 Git 与 GitHub 环境配置、Hugo 站点与主题搭建、到 Cloudflare Pages 自动部署 及 日常维护流程 的完整步骤。

一、 环境准备与 GitHub 基础配置

在开始搭建 Hugo 博客之前，请先配置好 Git 基础信息、网络代理，并准备好 GitHub 私有仓库及其访问令牌 (PAT)，确保后续推送与部署畅通无阻。

1.1 配置 Git 用户信息与凭据管理

打开终端（如 Cmder、Git Bash 或 PowerShell），设置 Git 全局用户名与邮箱：

1
2

git config --global user.name "your-username"
git config --global user.email "your-email@example.com"

配置 Windows 凭据管理器（wincred），以便自动保存凭据：

1

git config --global credential.helper wincred

1.2 配置 Git 网络代理（可选）

如在中国大陆地区遇到 GitHub 连接超时或网络阻塞，可配置 Git 使用本地代理（以常见的 HTTP 代理端口 10808 为例，请根据实际代理软件调整）：

1
2
3

# 设置 Git 全局代理
git config --global http.proxy http://127.0.0.1:10808
git config --global https.proxy http://127.0.0.1:10808

💡 提示：若遇到网络凭据交互阻塞，建议优先使用 HTTP 协议代理。

1.3 创建 GitHub 私有仓库 (Create a Private Repository)

1. 登录 GitHub 官网。
2. 在首页 Dashboard 的 Top repositories 区域右侧点击 New 按钮。
3. 基本配置：
   • Repository name *：填写 my-hugo-blog。
   • Choose visibility *：勾选 Private（私有仓库，保证源代码安全）。
4. 点击底部的 Create repository 按钮完成创建。

1.4 获取 GitHub 个人访问令牌 (Personal Access Token - Classic)

⚠️ 重要说明：GitHub 已不再允许使用账号明文密码进行命令行 Git 提交。在终端要求输入登录密码时，必须填写 Token 作为密码。

1. 点击 GitHub 右上角个人头像，进入 Settings ➔ Developer settings。
2. 在左侧菜单展开 Personal access tokens ➔ 点击 Tokens (classic)。
3. 点击右侧 Generate new token 按钮，选择 Generate new token (classic)。
4. 输入账户密码通过验证后，配置参数：
   • Note：填写说明（例如 my-hugo-blog-git-push）。
   • Expiration：选择有效期限（个人常用环境推荐选择 No expiration 永不过期）。
   • Select scopes：勾选 repo 选项（提供对私有仓库的完整控制权）。
5. 点击底部的 Generate token 按钮。
6. 非常重要：复制生成的 Token 字符串（格式如 ghp_xxxxxxxx...）并妥善保存。该 Token 仅会展示一次！

二、 创建 Hugo 网站与添加主题

2.1 初始化 Hugo 站点

在终端中切换至目标磁盘（例如 D:\）并初始化名为 my-hugo-blog 的 Hugo 站点：

1
2
3

cd /d D:\
hugo new site my-hugo-blog
cd my-hugo-blog

执行后，Hugo 会在 D:\my-hugo-blog 目录下生成基础的项目文件夹结构。

2.2 初始化 Git 仓库与添加 Stack 主题

进入项目根目录，初始化本地 Git 仓库，并以 Git Submodule 形式引入 Stack 主题：

1
2

git init
git submodule add https://github.com/CaiJimmy/hugo-theme-stack themes/hugo-theme-stack

验证方法：检查 D:\my-hugo-blog\themes\hugo-theme-stack 目录，若包含文件即代表下载成功。

三、 配置主题与创建第一篇文章

3.1 导入示例配置

Stack 主题自带了完整的示例站点配置，可直接复制到根目录使用：

1

cp -r themes/hugo-theme-stack/demo/* .

注意：如提示覆盖 hugo.toml 或 config.toml，请确认覆盖；或手动删除根目录原有的 hugo.toml。

3.2 新建博客文章

使用 Hugo 命令创建你的第一篇文章：

1

hugo new content posts/my-first-post.md

使用编辑器打开 D:\my-hugo-blog\content\posts\my-first-post.md，修改 Front Matter 中的草稿状态：

• 将 draft: true 修改为 draft: false（否则默认作为草稿，编译上线后不会显示）。

3.3 本地启动与预览

在终端运行以下命令启动本地预览服务器：

1

hugo server -D

打开浏览器访问 http://localhost:1313 即可预览效果。按 Ctrl + C 可退出预览。

四、 配置文件过滤（忽略无关文件）

如果使用了 Syncthing 等同步软件或进行了本地编译，需要通过 .gitignore 过滤无关的临时文件。

打开或新建项目根目录下的 .gitignore 文件，添加如下规则：

1
2
3
4
5
6

# 忽略 Syncthing 标记与配置文件
.stfolder/

# 忽略 Hugo 本地编译输出目录
public/
resources/

五、 推送到 GitHub 远程仓库

将本地项目关联并推送到刚才在 1.3 中创建的 GitHub 私有仓库：

1
2
3
4
5

git branch -M main
git add .
git commit -m "feat: initial commit with hugo and stack theme"
git remote add origin https://github.com/your-username/my-hugo-blog.git
git push -u origin main

凭据提示：在弹出提示输入账号密码时，Password 处请粘贴在 1.4 中保存的 Personal Access Token (PAT)。

六、 配置 Cloudflare Pages 自动部署

连接 GitHub 与 Cloudflare Pages，实现代码推送后自动触发远程编译上线。

6.1 创建 Cloudflare Pages 应用

1. 登录 Cloudflare 控制台。
2. 在左侧菜单点击 构建 ➔ 计算 ➔ Workers 和 Pages。
3. 点击 创建应用程序 ➔ 选择 Pages ➔ 导入现有 Git 存储库。
4. 授权并关联你的 GitHub 账号，选择私有仓库 your-username/my-hugo-blog。

6.2 设置构建参数与环境变量

在项目构建配置界面中填入以下参数：

• 构建命令：hugo
• 构建输出目录：public
• 根目录：（留空）

配置环境变量： 展开 变量和密钥 (Environment Variables) 区域，添加以下变量：

设置完成后点击 保存并部署。后续只要推送代码，Cloudflare 会在数十秒内自动完成编译上线。

七、 日常文章发布与更新流程

以后撰写新文章或修改站点配置时，只需遵循以下标准操作三步法：

1
2
3
4
5
6
7
8

# 1. 暂存改动
git add .

# 2. 提交更改记录
git commit -m "post: 发布新文章《标题》"

# 3. 推送到 GitHub（自动触发 Cloudflare 部署上线）
git push