如何搭建一个自己的博客

chenyongxi3 · 2026-02-26 15:53:30 · 科技·工程

写在前面

某高赞文章里写到：

已读。但是你可以用别的托管平台。

本教程教你搭建一个由 Hugo 和 Cloudflare Pages 驱动的博客，全免费。

本教程基于 Windows 10/11。

网站成品：https://blog.jqcyx.qzz.io/ 。后续教程中可以自己对照。

准备工作

你需要一个邮箱。

注册一个 GitHub 账号。官网链接。如果连不上请考虑科学上网、更换网络或使用 Watt Toolkit。

注册一个 Cloudflare 账号。官网链接。

还需要一个域名。当然，作为一名合格的 OIer，~~余额应该是零~~，我们可以用免费域名。

打开 DigitalPlat，里面的信息可以用美国人名生成器。

注册完之后会要求进行 GitHub OAuth，直接使用刚才注册的 GitHub 账号即可。

进入面板，点击右边 Domain Registration，填写你的域名名字，后缀的话 .dpdns.org 和 .qzz.io 是免费的，我选了 .qzz.io。

确定之后会让你填写 Name Server，打开 Cloudflare，点击主页 加入域，输入你的域名，然后点继续，Free 计划就可以。接着点击 继续前往激活，会看到给出了两个地址，填到 Nameserver configuration 的 Name Server 1 和 2 里。确认之后在 Cloudflare 继续。很快就好了。

本地环境配置

下载并安装 Git，安装途中留心添加到 PATH。

接下来安装 Hugo，以下三种方式任选其一。

使用 WinGet 安装（没有的请在这里下载）：

winget install Hugo.Hugo.Extended

使用 Chocolatey 安装（没有的请在 PowerShell 中运行以下代码）

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

安装：

choco install hugo-extended

使用 Scoop 安装（没有的请在 PowerShell 中运行以下代码）

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

安装：

scoop install hugo-extended

为了避免你以后找了个稀奇古怪的主题又来问我没依赖，强烈建议再安装 Dart Sass 和 Go。

Dart Sass 的安装：

Scoop

scoop install sass

Chocolatey

choco install sass

开始操作

Hugo 官方提供了许多的主题，我一开始用的是 PaperMod，简约、大气、好看……但是没有 \LaTeX 支持！！！我和豆包进行了 2.5 小时的会诊才加上去，文件被改得不成样子，于是一气之下换到了 Stack。

~~然后因为官方提供的 \LaTeX CDN 是 jsdelivr 的，国内可用性太差又进行了 2.5 小时的会诊。~~

接下来会讲解使用 Stack 入门模板和 PaperMod 模板进行部署。

Stack

修改

打开官方仓库，点击 Code，然后 Donwnload ZIP。

下载之后，删除 .github、.devcontainer、.vscode、public、resources 文件夹和 README.md 文件。删完之后你的文件树应该是

hugo-theme-stack-starter-master
├─assets
│  ├─img
│  └─scss
├─config
│  └─_default
└─content
    ├─categories
    │  └─example-category
    ├─page
    │  ├─archives
    │  ├─links
    │  └─search
    └─post
        ├─hello-world
        ├─image-gallery
        ├─markdown-syntax
        ├─math-typesetting
        └─shortcodes

。

首先新建 data 文件夹，在里面新建 external.toml，粘贴以下内容：

KaTeX = [
    { src = "https://cdn.jsdmirror.cn/npm/[email protected]/dist/katex.min.css", integrity = "sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV", type = "style" },
    { src = "https://cdn.jsdmirror.cn/npm/[email protected]/dist/katex.min.js", integrity = "sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8", type = "script", defer = true },
    { src = "https://cdn.jsdmirror.cn/npm/[email protected]/dist/contrib/auto-render.min.js", integrity = "sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05", type = "script", defer = true },
]

Cactus = [
    { src = "https://latest.cactus.chat/cactus.js", type = "script" },
    { src = "https://latest.cactus.chat/style.css", type = "style" },
]

[PhotoSwipe]
    Style    = "https://cdn.jsdelivr.net/npm/[email protected]/dist/photoswipe.css"
    Core     = "https://cdn.jsdelivr.net/npm/[email protected]/dist/photoswipe.esm.min.js"
    Lightbox = "https://cdn.jsdelivr.net/npm/[email protected]/dist/photoswipe-lightbox.esm.min.js"

这一步是为了把 \KaTeX 换成国内镜像。

删除 config/_default/_language.toml（~~反正多语言你也不会写~~）

打开 config/_default/config.toml，

把 baseurl 改成你的域名（挖个坑，等会儿填），

title 改成你的网站名，

defaultContentLanguage 改成 "zh-cn"，

hasCJKLanguage 改成 true。

打开 config/_default/menu.toml，这控制了网页左上角的社交图标。

实例：

[[social]]
    identifier = "github"
    name       = "GitHub"
    url        = "https://github.com/jqcyx"

    [social.params]
        icon = "brand-github"

其中 identifier 是给自己看的标识符，

name 是现实的名称，

url 是对应链接，

icon 可选，加了会覆盖 name。想要放自己的 icon 可以扔到 /assets/icons 里。

打开 config/_default/params.toml，

since 填建站的年份，
下面 [article] 把 math 改成 true，启动 \LaTeX。

[sidebar]
    emoji    = "💤"
    subtitle = "已完成今日我对着铁质的机箱踢了五下然后把那堆代码在内存中删了一下然后把椅子砸在了地板上大学习"
    avatar   = "img/avatar.png"

emoji 是显示在头像旁边的，

subtitle 是你的个性签名，

avatar 是头像，放在 /assets/img 里。

最下面的 commemts 选项是重头戏，我们使用 Giscus，所以把 provider 改成 "giscus"。

接下来在 Github 新建一个 Public 仓库，并且把官方应用安装到你的仓库，然后在 Setting 里启用 Discussion，打开官网，按默认值填下去。最后有一段代码，按这个格式粘贴到你的 provider 下面：

    [comments.giscus]
        repo             = 生成的 data-repo
        repoID           = 生成的 data-repo-id
        category         = 生成的 data-category
        categoryID       = 生成的 data-category-id
        mapping          = "title"
        lightTheme       = "light"
        darkTheme        = "dark_dimmed"
        reactionsEnabled = 1
        emitMetadata     = 0
        inputPosition    = "top"
        lang             = "zh-CN"
        strict           = 0
        loading          = "lazy"

打开 content 文件夹，作为本土化的一环，把 _index.md 里的 name 换成 主页。

categories 建议满门抄斩之前留一个解刨参考。详解：

---
title: 题解
description: 如果你是来找我的黑历史的，那你赢了。
image:

style:
    background: "#2a9d8f"
    color: "#fff"
---

title 是这个 category 的名称，description 是描述，image 是封面，background 是标签的底色，color 是标签字的颜色。

page 是各种页面，请参考官方文档进行修改。反正我没改（逃

本土化的话修改每个文件夹里 index.md 里的 name。

post 是重点，编写文章时，新建一个文件夹，里面放入 index.md，开头这么写：

---
title: 你的标题
date: 你的发布时间（形如2026-02-25T16:42:04+08:00，自己理解）
draft: false
categories: 在哪些categories里，使用列表，形如 ['1','2','3']
tags: 标签，同 categories 的格式
---

插入文件可以把资源放在当前文件夹里，引用写成[描述](文件名)。

就这么简单。本地预览可以在 Powershell 里运行

hugo server

。

接下来该部署了。

部署

在 Powershell 运行

git config --global user.name 你的用户名
git config --global user.email 你的邮箱
ssh-keygen -t rsa -C 你的邮箱

一路 yes，打开你的用户目录下的 .ssh 文件夹，把 ip_rsa.pub 里的东西复制走。

打开 GitHub，选择 Settings，找到 SSH and GPG keys，点 New SSH Key，粘进去并 Add。

注意： 如果你用了 Watt Toolkit 加速 GitHub 访问，把它关掉！把它关掉！把它关掉！ 它会把 GitHub 重定向并且改证书，导致验证失败。在你没关掉之前，千万千万不要进行下一步！！！

本地运行

ssh -T [email protected]

如果链接成功，则有 You've successfully authenticated, but GitHub does not provide shell access 输出。

新建一个仓库，Public/Private 均可。建议还是私有好。

回到你的博客根目录，运行

git init
git add .
git commit -m "你的推送内容"
git remote add origin [email protected]:你的用户名/你的仓库名.git
git push -u origin main

检查你的仓库，看看文件有没有传上去。

打开 Cloudflare，选择 Workers 和 Pages，点击 创建应用程序，点击下方 Pages 旁边的 开始使用，点 导入现有 Git 存储库，把你的 GitHub 账号加进去，选择你的存储库，框架预设选 Hugo，保存并部署。

然后会弹出部署成功的页面，点击添加自定义域名，可以是子域名，例如我的域名是 example.com，我想用 blog 子域名，你就填 blog.example.com。

注意刚才跳过的一步：把刚才留着的 baseurl 填上去！比如你填 blog.example.com，那 baseurl 的内容应该一样！

自动添加好记录就可以访问了。

如果后面写了新文章，就在 Powershell 里执行：

git add .
git commit -m "你的推送内容"
git push

注意关掉你的 Watt Toolkit。

还有，Cloudflare Pages 一个月免费构建 500 次。（不会有人更新这么多吧……）

PaperMod

学会了这个应该其他也会了。

在任意目录下运行：

hugo new site 网站名称

找到官方页面里的 PaperMod，自行查阅添加方式，例如用子模块（假设你的 git init 已经跑过了）：

git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

你可以自己看看每个主题的格式，例如 PaperMod 就是把附件放到 assets 里，可以直接访问。写作可以用这个命令：

hugo new content content/posts/文章名.md

Frontmatter 会自己写好，记得把 draft 改成 false。

好的，现在你已经学会了，接下来完成十道黑题犒劳一下自己吧。