从零搭建个人博客：Hugo + GitHub + Vercel

Tue, 28 Apr 2026 00:00:00 +0000

搭建个人博客的过程，本质上是在完成一条很清晰的工作流：

本地写作 -> Hugo 生成静态网页 -> GitHub 托管代码 -> Vercel 自动部署 -> 自定义域名访问。

这篇文章整理了一套通用流程，适合想用 Markdown 长期记录学习、科研、项目、生活和作品的人。示例以 Hugo + Stack 主题为主，换成 PaperMod 等其他 Hugo 主题时，整体思路也基本一致。

1. 为什么选择静态博客

静态博客不依赖数据库，文章通常就是一份份 Markdown 文件。它的优点很直接：

维护成本低，适合长期写作。
速度快，部署后访问的是静态页面。
内容可版本管理，每次修改都能通过 Git 追踪。
可以用 GitHub 和 Vercel 免费完成大部分个人站点需求。

如果你的目标是记录学习笔记、论文阅读、项目复盘、作品展示或个人主页，Hugo 是一个很稳妥的选择。

2. 准备工具

开始前需要准备这些工具：

Hugo：静态网站生成器。
Git：版本管理工具。
GitHub 账号：用于托管博客源码。
Vercel 账号：用于自动部署博客。
一个可选的自定义域名：例如 blog.example.com。

Hugo 可以从官网安装：

Windows 用户可以到 Hugo 的 GitHub Releases 页面下载对应版本。一般建议选择 extended 版本，后续处理主题样式时兼容性更好。

下载后将 Hugo 解压到合适目录，并把 Hugo 所在目录加入系统环境变量 PATH。

安装完成后，在终端运行：

`1`	`hugo version`

如果能看到类似 hugo v0.x.x-extended windows/amd64 的输出，就说明安装成功。

3. 创建 Hugo 项目

选择一个合适的工作目录，然后创建站点：

cd D:\work\files
hugo new site my-blog
cd my-blog
git init

执行后，Hugo 会生成一个基础目录结构：

my-blog/
├── archetypes/
├── assets/
├── content/
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
└── hugo.toml

其中最常用的是：

content/：存放文章和页面。
config/ 或 hugo.toml：存放站点配置。
themes/：存放主题。
static/：存放不需要 Hugo 处理的静态资源，例如图片、favicon、文件下载资源。
public/：运行 hugo 后生成的静态网页目录。

4. 安装主题

Hugo 本身负责把 Markdown 生成网页，页面样式主要由主题决定。可以在 Hugo 官方主题站选择自己喜欢的主题：

`1`	`https://themes.gohugo.io/`

以 Stack 主题为例，在博客根目录执行：

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

如果使用 PaperMod，命令类似：

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

使用 Git submodule 的好处是：主题代码和自己的博客内容分开管理，后续更新主题也更清晰。

5. 配置 Hugo

Hugo 可以使用单文件配置，也可以使用拆分式配置。个人博客更推荐拆分式配置，结构更清楚：

config/
└── _default/
    ├── hugo.toml
    ├── languages.toml
    ├── menu.toml
    ├── params.toml
    └── markup.toml

一个基础的 hugo.toml 可以这样写：

baseURL = "https://blog.example.com/"
languageCode = "zh-cn"
title = "My Blog"
theme = "hugo-theme-stack"

defaultContentLanguage = "zh"
hasCJKLanguage = true

[pagination]
    pagerSize = 10

[permalinks]
    post = "/p/:slug/"
    page = "/:slug/"

[outputs]
    home = ["HTML", "RSS", "JSON"]

常见的 params.toml 配置可以包括：

mainSections = ["research", "life", "invest"]
rssFullContent = true
favicon = "img/avatar.png"

[footer]
    since = 2026

[sidebar]
    subtitle = "记录研究、学习与生活"
    avatar = "img/avatar.png"

[article]
    [article.license]
        enabled = false

[widgets]
    homepage = [
        { type = "search" },
        { type = "archives", params = { limit = 5 } },
        { type = "categories", params = { limit = 10 } },
        { type = "tag-cloud", params = { limit = 10 } },
    ]
    page = [{ type = "toc" }]

[comments]
    enabled = false
    provider = ""

菜单可以单独放在 menu.toml：

[[main]]
    name = "首页"
    url = "/"
    weight = 1

[[main]]
    name = "文章"
    url = "/research/"
    weight = 2

[[main]]
    name = "归档"
    url = "/archives/"
    weight = 3

[[main]]
    name = "关于"
    url = "/about/"
    weight = 4

配置完成后，可以先本地预览：

`1`	`hugo server -D`

打开浏览器访问：

`1`	`http://localhost:1313/`

如果页面能正常显示，说明 Hugo 和主题已经跑通。

6. 规划内容目录

个人博客的核心是内容。一个简洁的目录可以这样规划：

content/
├── research/
│   ├── _index.md
│   └── first-post.md
├── life/
│   └── _index.md
├── invest/
│   └── _index.md
├── page/
│   ├── about/
│   │   └── index.zh.md
│   └── archives/
│       └── index.zh.md
└── _index.zh.md

可以把不同类型的文章放进不同栏目：

research/：科研记录、论文阅读、技术笔记。
life/：生活记录、读书笔记、阶段总结。
invest/：投资学习、市场观察、方法论整理。
page/about/：关于页面。
page/archives/：归档页面。

不建议随意删除 _index.md、about、archives 这类文件，因为它们常常和栏目页、菜单、归档页有关。

7. 新建文章

可以用 Hugo 命令新建文章：

`1`	`hugo new research/first-post.md`

一篇文章通常包含 front matter，也就是 Markdown 文件顶部的元信息：

---
title: "第一篇博客"
date: 2026-04-28
draft: false
tags: ["Hugo", "博客"]
categories: ["科研学习"]
description: "记录第一篇博客的写作和发布过程。"
---

这里写正文内容。

几个常用字段的含义：

title：文章标题。
date：发布时间。
draft：是否为草稿，true 不会正式发布，false 可以发布。
tags：标签。
categories：分类。
description：文章摘要，常用于列表页和搜索结果。

写作时建议遵循一个简单原则：先把内容讲清楚，再考虑样式。Hugo 的优势就是让你把注意力放在 Markdown 和长期积累上。

8. 生成静态网页

本地确认没问题后，运行：

hugo

Hugo 会生成 public/ 目录，里面就是可以部署到服务器的静态网页。

如果本地预览时想看到草稿，可以运行：

`1`	`hugo server -D`

如果只想预览正式发布内容，可以运行：

`1`	`hugo server`

9. 推送到 GitHub

在 GitHub 创建一个新仓库后，把本地项目推送上去：

git add .
git commit -m "init blog"
git branch -M main
git remote add origin https://github.com/your-name/your-blog.git
git push -u origin main

以后每次更新文章，大致就是：

1
2
3

git add .
git commit -m "update blog"
git push

如果主题使用了 submodule，克隆仓库时建议使用：

`1`	`git clone --recurse-submodules https://github.com/your-name/your-blog.git`

如果已经克隆但主题目录为空，可以运行：

`1`	`git submodule update --init --recursive`

10. 使用 Vercel 部署

Vercel 可以直接连接 GitHub 仓库。基本流程是：

登录 Vercel。
选择 Import Git Repository。
选择 GitHub 中的博客仓库。
Framework 选择 Hugo。
Build Command 填 hugo。
Output Directory 填 public。
点击 Deploy。

部署成功后，Vercel 会生成一个临时访问域名。之后只要 GitHub 仓库有新的提交，Vercel 就会自动重新构建和发布。

如果构建失败，优先检查这几项：

Hugo 版本是否和本地一致。
主题 submodule 是否正确拉取。
theme 配置是否和 themes/ 下的目录名一致。
Markdown front matter 是否格式正确。
图片路径是否写对。

11. 绑定自定义域名

如果已经有自己的域名，可以在 Vercel 项目设置中添加域名，例如：

`1`	`blog.example.com`

然后按照 Vercel 提示，到域名服务商的 DNS 控制台添加解析记录。常见配置是：

`1`	`blog CNAME cname.vercel-dns.com`

等待 DNS 生效后，就可以通过自己的域名访问博客。

如果使用根域名，例如 example.com，Vercel 可能会提示使用 A 记录或其他方式。以 Vercel 页面给出的提示为准。

12. 日常维护流程

博客真正有价值的地方不是一次搭建完成，而是后续能稳定写下去。一个简单的维护流程是：

1
2
3

cd D:\work\files\my-blog
hugo new research/new-note.md
hugo server -D

写完并确认预览没问题后：

1
2
3

git add .
git commit -m "add new post"
git push

然后等待 Vercel 自动部署即可。

13. 后续可以逐步完善什么

初期不建议一次性配置太复杂。可以按这个顺序逐步完善：

先让博客能稳定构建和访问。
调整主题外观、头像、菜单和首页。
完善文章分类、标签和归档。
添加搜索功能。
添加评论系统，例如 Giscus、Waline 或 Disqus。
优化 SEO、站点地图、RSS 和 Open Graph。
后续再考虑 Notion 同步、AI 搜索或自动化发布。

14. 一句话总结

Hugo 负责把 Markdown 变成静态网页，GitHub 负责保存和管理源码，Vercel 负责自动构建和发布，自定义域名负责让博客拥有稳定入口。

整条链路跑通之后，写博客就会变成一件很轻的事：打开 Markdown，写下内容，提交到 GitHub，剩下的交给自动部署。

Hugo on Ziyang Yao