个人博客搭建

1.实现目标

我曾经用不同的技术方式搭建过很多次Blog，也用过在线的产品，其实最大的问题还是没有坚持下来，这两年迷上了写markdown文档，积攒了很多，喜欢这种简洁的形式，有些markdown内容也希望以Blog的形式在网上发布，也方便自己随时随地查阅。正好发现Cloudflare这个宝藏网站，所以打算再搞一回。

大致的设想是：

我本地写 Markdown → 推送到 GitHub（私有仓库） → Cloudflare Pages 自动编译 Hugo（一个开源Blog产品） → 自动生成网站 + 自动部署 → 绑定我的顶级域名 + 免费HTTPS
我只做一件事：写 .md 文件，剩下全自动化

2. 安装Go环境

新版Hugo需要安装Go环境，官方下载地址（选择 Windows - MSI 安装包）： https://go.dev/dl/

直接下最新版，文件名类似： go1.23.4.windows-amd64.msi

安装时双击 → 一路下一步，不要改路径，自动配置环境变量。

注意

其实这个装不装影响不大，我是过程中有些来回调试时，遇到了需要Go环境的情况，所以当时装了一下，可以先跳过这块，后面有需要的话再安装。

3. 本地搭建 Hugo 博客（Win环境）

3.1 基于Hugoplate模板

手动下载

https://github.com/gohugoio/hugo/releases/download/v0.161.1/hugo_0.161.1_windows-amd64.zip
然后解压拷贝到D盘，重命名为D:/hugo
并把其添加到环境变量的Path中

新建博客

以下操作均在powershell中执行

cd D:\Github-Repo

# 1. 克隆整个模板（不要手动创建空项目）
git clone https://github.com/zeon-studio/hugoplate.git my-blog
cd my-blog

# 2. 删除原有的 git 记录（这样您就能用自己的仓库）
rm -Recurse -Force .git

# 3. 安装所有依赖（Node 包 + Hugo 模块）
npm install

本地测试

# 运行项目设置脚本（这会自动配置好主题结构）
npm run project-setup

# 启动开发服务器
npm run dev

启动后应该能看到如下内容

[1]                   │ EN
[1] ──────────────────┼────
[1]  Pages            │ 90
[1]  Paginator pages  │  0
[1]  Non-page files   │  0
[1]  Static files     │  4
[1]  Processed images │ 79
[1]  Aliases          │  1
[1]  Cleaned          │  0
[1]
[1] Built in 3442 ms
[1] Environment: "development"
[1] Serving pages from disk
[1] Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
[1] Web Server is available at //localhost:1313/ (bind address 127.0.0.1)

打开 http://localhost:1313，您应该能看到一个完整的演示网站。

3.2 基于Hextra模板

安装方法

访问模板仓库：打开 Hextra Starter Template。
使用模板：点击绿色的 Use this template 按钮，创建一个属于我自己的新仓库。
克隆到本地：将我刚创建的新仓库 git clone 到本地电脑。

启动测试

# 进入项目目录
cd blogsite
# 启动本地服务器
hugo server --logLevel debug --disableFastRender -p 1313

#如果遇到被墙的问题
git config --global url."git@github.com:".insteadOf "https://github.com/"

现在打开浏览器访问 http://localhost:1313，一个现代化的站点就已经跑起来了

备注

比较之后，我最终还是选择了Hugo模板，简介，更符合我的口味

4.配置内部文档目录（Hugo模板）

原本我希望利旧之前的文档目录Blog，但是在后面和Cloudflare集成自动流程的时候反而搞得复杂了，所以我将原来Blog中的内容全部放到blogsite/content/blogsite下，并调整了hugo.yaml配置文件

module:
  imports:
    - path: github.com/imfing/hextra
    
  # 关键配置：将外部目录挂载到 content
  mounts:
	- source: content  #这个不配置则该目录下的文件无法被编译加载
      target: content
      files:
        - "*"         #包含 content/ 下所有文件（不含子文件夹内容）
        - "!docs/**"   #但排除 content/docs/（模板 demo 内容，不需要发布）
        - "!blogsite/**"  #但排除 content/blogsite/（由下面第二个挂载规则单独处理）
    - source: content/blogsite
      target: content/docs
      excludeFiles: 
        - ".obsidian/**"
        - "Clippings/**"
        - "copilot/**"
        - ".gitignore"

5.其他配置

5.1 标题和目录显示调整

在 Obsidian 的较新版本中，它默认会开启 “显示内联标题 (Show Inline Title)”。这个功能会自动抓取我的“文件名”，并以大标题的形式虚拟显示在编辑区的最顶端。如果我自己在正文里又手写了一个 # title，在 Obsidian 里看起来就像是出现了双标题。

所以我们首先需要关闭 Obsidian 的虚拟标题

打开 Obsidian 设置 (Settings)。
进入 外观 (Appearance)。
找到 显示内联标题/页内标题 (Show inline title)，将其 关闭 (Off)。

现在 Obsidian 只会显示我手写的 # title，两边就对齐了。

然后我们自己手动添加一级标题，他将作为文档的Title显示，然后左右的二级标题会自动变成Hugo的右侧大纲标题。这样样式就统一了。

6.集成Cloudflare

6.1 创建项目

登录 Cloudflare Dashboard。
在左侧菜单选择 Workers & Pages -> Create application。
在最下方有一个想要部署 Pages？开始使用 -> 点击开始使用
进入6.2 构建设置

6.2 配置构建设置（关键）

在 Build settings 界面，按照以下参数填写：

配置项	填写内容
框架预设/Framework preset	选择 `Hugo`
构建命令/Build command	`hugo --gc --minify`
构建输出目录/Build output directory	`public`

6.3 设置环境变量

点击 Environment variables (advanced)，添加以下变量以确保环境一致性：

HUGO_VERSION: 设置为 0.161.1（或者我本地 hugo version 显示的版本）。这是为了防止 Cloudflare 使用过旧的默认版本导致 Hextra 模板不兼容。
NODE_VERSION: 如果我的模板涉及特殊的 NPM 处理，建议设为 20 或以上，如24.14.1。

6.4. 自动化流程验证

点击 Save and Deploy 后，Cloudflare 会开始第一次构建。

实时日志：我可以看到 Cloudflare 正在克隆仓库、安装 Hugo 并执行渲染。
预览地址：构建完成后，我会得到一个 *.pages.dev 的二级域名。

6.5 绑定顶级域名 & 开启极速访问

由于我已经是 Cloudflare 用户，绑定域名非常简单：

在 Pages 项目页面，点击 Custom domains 选项卡。
点击 Set up a custom domain，输入我的域名（例如 blog.yourdomain.com）。
自动解析：如果我的域名 DNS 托管在 Cloudflare，它会自动为我创建 CNAME 记录。
开启小云朵：确保 DNS 记录中的“Proxy status”是 Proxied，这样我的博客就能享受 Cloudflare 全球 CDN 加速和免费的 SSL 证书。