使用Hugo + Decap CMS + GitLab + Cloudflare Pages搭建博客的折腾过程

主要在折腾什么

除了把源码上传到仓库以及把博客部署在 CF Pages 上面这些简单的傻瓜式操作以外，很多人应该会认为搭建 Hugo 站点应该是占大头的，的确，这确实是最主要的工作，但是并不难，因为有很多现成的主题可以使用，美观，许多功能开箱即用，且有文档以及网上使用同主题的博客可供参考，比如你现在正在浏览的博客使用的是 Stack 主题，项目的文档在这里 Stack | Card-style Hugo theme designed for bloggers

回答“折腾什么”的问题，如果我仅仅是为了写怎么怎么修改配置然后 hugo serve 得到一个博客，那我着实没有必要写这篇文章，于是我们在标题中看到 Decap CMS，这便是这篇文章的主题

说实话，如果你看完这篇文章，你大概会觉得没有什么复杂的，但就在这看似简单的过程，我本人踩了很多坑，折腾了几个晚上，求助了d老师多次也没成功，最终还是靠自己啃文档解决了问题，然后才有了这篇文章

难在哪里

如标题所见，我将代码存放在 GitLab 上而不是 GitHub ，而网上的教程都是关于 GitHub 的，比如这一篇 https://www.ixam.net/zh-hans/blog/2025/08/blog-made-by-hugo-github-dcapcms-cloudflarepages/ 以及这一篇 https://sheng.page/posts/adding-decap-cms-to-hugo-on-cloudflare-pages/ ，所以我几乎是摸着石头过河

为什么选用 GitLab

最开始的原因很简单，被 GitHub 封号封怕了，在此之前我已经被封禁了两个账号，其中有一个甚至是刚注册还什么都没干就被封，你在b站上也能找到一些好端端的就被封禁的例子。其言“标记”，但是申诉需要非大陆手机号验证，所以就卡住了，我也有尝试过接码平台，但是发不出短信（反正我是这样），而且好像它还要求你在6个月内申诉，过时可能永远不会再给你解封，近乎无解

但是选用了 GitLab 之后有一个好处，就是，如果你看了上面两篇针对GitHub的文章就可以发现，GitHub Oauth 需要 server-side 交换 secret ，不可能在浏览器端完成，处理的方法是用 CF 的 Pages Functions ，而 GitLab 可以 client-side 验证，如此便不花费 Functions 额度（虽然原本花费的也微不足道就是了）

上手过程

使用 Hugo 建立站点

网上教程很多，此处不再赘述

安装 Decap CMS

创建 index.html

创建 static/admin/index.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="shortcut icon" href=/img/favicon.ico>
    <title>内容管理</title>
  </head>
  <body>
    <script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
  </body>
</html>

创建 config.yml

创建 static/admin/config.yml

下面是本人自用的配置，更详细的配置项见官方文档：https://decapcms.org/docs/configure-decap-cms/

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
backend:
  name: gitlab  # 设置 GitLab 作为 Decap CMS 的后端
  repo: owner-name/repo-name  # 你的博客代码仓库路径
  branch: main  # 一般是 main
  auth_type: pkce # 照填不用动
  app_id: your-app-id # 获取方式见后文

media_folder: "static/uploads"
public_folder: "/uploads"

collections:
  - name: "posts"
    label: "文章"
    folder: "content/posts"
    create: true
    extension: md
    format: yaml-frontmatter
    identifier_field: title
    slug: "{{year}}-{{month}}-{{day}}-{{fields.slug}}"
    editor:
      preview: true
    fields:
      - {label: "标题", name: "title", widget: "string"}
      - {label: "描述", name: "description", widget: "string", required: false}
      - {label: "slug", name: "slug", widget: "string", required: true}
      - {label: "发布日期", name: "date", widget: "datetime", default: "{{now}}"}
      - {label: "上次修改", name: "lastmod", widget: "datetime", default: "{{now}}", date_format: "YYYY-MM-DD", time_format: false}
      - {label: "阅读时间", name: "readingTime", widget: "boolean", default: true}
      - {label: "封面图", name: "image", widget: 'image', required: false}
      - {label: "分类", name: "categories", widget: "list", required: false}
      - {label: "标签", name: "tags", widget: "list", required: false}
      - {label: "目录", name: "toc", widget: "boolean", default: true}
      - {label: "评论", name: "comments", widget: "boolean", default: true}
      - {label: "公式渲染", name: "math", widget: "boolean", default: true}
      - {label: "license", name: "license", widget: "string", required: false}
      - {label: "草稿", name: "draft", widget: "boolean", default: true}
      - {label: "关键词", name: "keywords", widget: "list", required: false}
      - {label: "正文", name: "body", widget: "richtext"}

  - name: "pages"
    label: "页面"
    folder: "content/page"
    create: true
    extension: md
    format: yaml-frontmatter
    identifier_field: title
    slug: "{{year}}-{{month}}-{{day}}-{{fields.slug}}"
    editor:
      preview: true
    fields:
      - {label: "标题", name: "title", widget: "string"}
      - {label: "描述", name: "description", widget: "string", required: false}
      - {label: "slug", name: "slug", widget: "string", required: true}
      - {label: "发布日期", name: "date", widget: "datetime", default: "{{now}}"}
      - {label: "上次修改", name: "lastmod", widget: "datetime", default: "{{now}}", date_format: "YYYY-MM-DD", time_format: false}
      - {label: "阅读时间", name: "readingTime", widget: "boolean", default: true}
      - {label: "封面图", name: "image", widget: 'image', required: false}
      - {label: "分类", name: "categories", widget: "list", required: false}
      - {label: "标签", name: "tags", widget: "list", required: false}
      - {label: "目录", name: "toc", widget: "boolean", default: true}
      - {label: "评论", name: "comments", widget: "boolean", default: true}
      - {label: "公式渲染", name: "math", widget: "boolean", default: true}
      - {label: "license", name: "license", widget: "string", required: false}
      - {label: "草稿", name: "draft", widget: "boolean", default: true}
      - {label: "关键词", name: "keywords", widget: "list", required: false}
      - {label: "正文", name: "body", widget: "richtext"}

💡 提示
static 目录包含在构建站点时将复制到 public 目录的文件，例如 favicon.ico、robots.txt 和用于验证站点拥有权的文件。

创建 GitLab OAuth 应用

登录 GitLab

进入 Settings → Applications（或直接访问 https://gitlab.com/-/profile/applications ）

新建应用

Name：Decap CMS
📌 重要
取消勾选 Confidential
Redirect URI：填入 https://你的博客地址/admin ，比如 https://blog.your-site.com/admin
Scopes：勾选 api

获得 app id

点击 Save application，记录下 Application ID

将记录下的 Application ID 填入 config.yml 中的 app_id: 后

部署到 CF Pages 上

构建设置

构建命令：hugo --minify
构建输出：public
环境变量：HUGO_VERSION = 0.163.3

点击 保存并部署，等待首次部署

成功后会分配一个 *.pages.dev URL

绑定独立域名

如果想要优选可以参考cm的博客：https://blog.cmliussss.com/p/BestWorkers/#%E4%B8%BA-Pages-%E9%A1%B9%E7%9B%AE%E4%BD%BF%E7%94%A8%E4%BC%98%E9%80%89%E5%9F%9F%E5%90%8D

进入 DecapCMS 管理界面

在浏览器打开 https://blog.your-site.com/admin
点击 “Login with GitLab” 按钮，授权 GitLab OAuth
第一次会出现 GitLab 的“是否授权该应用？”提示，点击 Authorize

大功告成

一个带有 Decap CMS 的 Hugo 博客搭建完成，你可以使用 CMS 管理文章等内容