Skip to content
Docs
博客文章
个人博客搭建

个人博客搭建

1.实现目标

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

2. 安装Go环境

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

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

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

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

3.1 基于Hugoplate模板

image.png

手动下载

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模板

image.png

安装方法

  1. 访问模板仓库：打开 Hextra Starter Template。
  2. 使用模板：点击绿色的 Use this template 按钮，创建一个属于你自己的新仓库。
  3. 克隆到本地：将你刚创建的新仓库 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，一个现代化的站点就已经跑起来了

4. 配置外部文档目录（废弃，维护复杂）

默认情况下，所有的文档需要放到模板工程的目录下，类似这样

你的电脑
└── blogsite/               <-- 这是 Hugo 完整项目（含主题、配置、markdown）
    ├── content/
    │   └── posts/          <-- 你所有的 .md 文章放这里！也有可能是docs目录
    ├── hugo.toml
    └── ... 其他文件

但我已经在另一个工程中存放了所有的markdown文档，比如这样

我的目录
Github-Repo/
	├── Blog/       我的markdown文档存放地
    │    ├─ 01-博客/
    │    ├─ 02-Youtube/
	│    ├─ 03-技术/	    子文档分类目录
    │    └─ ....  其他的，有些是不需要的
	└── blogsite/   hugo的工程，基于某个模板

所以我需要我的blog站点工程支持外部文档目录

步骤 1：打开你的 Hugo 配置文件

打开 blogsite/hugo.yaml

步骤 2：添加这一行（核心！）

在 Hugo 中，默认的文档存放路径是 content/ 目录。如果你希望 Hugo 读取 blogsite/ 之外的文件夹（即上一级的 Blog/），最优雅且稳定的做法是使用 Hugo 模块挂载（Mounts）。

通过配置 module.mounts，你可以将外部目录虚拟映射到 Hugo 的内容系统里，而无需移动物理文件。

  # 关键配置：将外部目录挂载到 content
  mounts:
    - source: ../Blog
      target: content/docs  #注意这里映射到该模板对应的文档所在文件夹
      excludeFiles:         #这里列出排除的目录或文件
        - ".obsidian/**"
        - "Clippings/**"
        - "copilot/**"
        - ".gitignore"

步骤3： 在每个子文件夹下增加 _index.md文件

_index.md 的主要作用

  • 定义目录的元数据：你可以为这个分类设置标题（Title）、权重（Weight，决定排序）、是否显示在菜单中等。
  • 存放分类页的内容：当你点击导航栏的“技术”分类时，页面上方显示的介绍文字就写在 _index.md 的内容区。
  • 触发 Hextra 侧边栏：对于你使用的 Hextra 模板，如果子文件夹里没有 _index.md，左侧的树状菜单可能无法正确展开或显示该分类的名称。

我们可以按如下方式配置

在 Blog/01-博客/_index.md 中：

---
title: 博客文章
weight: 1
---

在 Blog/03-技术/_index.md 中：

---
title: 技术笔记
weight: 2
---
# 这里是技术笔记
这里可以写一些关于技术栈的总体介绍。

4.配置内部文档目录

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

module:
  imports:
    - path: github.com/imfing/hextra
    
  # 关键配置：将外部目录挂载到 content
  mounts:
    - source: content/notes
      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 创建项目

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

6.2 配置构建设置（关键）

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

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

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 用户，绑定域名非常简单：

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