如何用hugo构建自己的博客

fry

2025-03-31 约 1813 字预计阅读 4 分钟

这篇写给谁

如果你也想搭一个自己的博客，而且希望：

源码放在一个仓库里，方便自己慢慢写
最终网站自动部署到 yourusername.github.io
尽量少踩 GitHub Pages 和 Hugo 的坑

那这套流程会比较顺手。

我这里用的是两个仓库：

私有仓库：blogsource
公开仓库：yourusername.github.io

其中公开仓库的名字最好直接用 yourusername.github.io。如果你是第一次弄 GitHub Pages，建议就按这个来，最省事。

开始前先准备好

先安装这几个东西：

Hugo
Git
一个你顺手的编辑器，比如 VS Code

然后在本地找一个文件夹专门放博客项目，比如我的是 D:\MyBlog。

一个小提醒

整个流程里，尽量都在本地改文件，再通过 Git 推上去。不要一会儿本地改、一会儿又去 GitHub 网页上改，不然很容易把仓库状态搞乱。

整体思路

这套博客的结构其实很简单：

blogsource 用来放 Hugo 源码
yourusername.github.io 用来放生成后的静态网页
本地写文章，推送源码
GitHub Actions 自动构建并部署到公开仓库

如果你刚开始不想上自动化，也可以先手动部署一遍，确认网站能跑起来，再加 Actions。

1. 初始化 Hugo 项目

先在终端里进入你准备放博客的目录，例如：

cd D:\MyBlog

然后创建 Hugo 项目：

hugo new site blogsource
cd blogsource
git init
git remote add origin https://github.com/yourusername/blogsource.git

这里把 yourusername 换成你自己的 GitHub 用户名。

2. 添加主题

我这里用的是 LoveIt 主题，你也可以换成自己喜欢的主题。

git submodule add https://github.com/dillonzq/LoveIt themes/LoveIt

用子模块的好处是后面更新主题会比较方便。

3. 配置 `hugo.toml`

先写一个最基础的配置：

baseURL = "https://yourusername.github.io/"
title = "My Blog"
theme = "LoveIt"
publishDir = "public"

这里有两个地方要特别注意：

baseURL 要换成你自己的地址，而且建议保留最后那个 /
publishDir = "public" 表示 Hugo 生成出来的静态文件会放到 public/

4. 先创建一篇测试文章

先确认 Hugo 本身是正常工作的：

hugo new posts/hello-world.md

然后编辑 content/posts/hello-world.md，写成这样：

+++
title = "Hello World"
date = "2024-01-01T00:00:00+08:00"
draft = false
+++

这是我的第一篇博客。

如果你文章里有 draft = true，那默认不会显示出来，这个地方很容易忘。

5. 本地预览

在项目根目录运行：

hugo server -D

然后打开：

http://localhost:1313

如果你能正常看到首页和刚才那篇测试文章，说明本地 Hugo 已经没问题了。

6. 先把源码推到私有仓库

这一步是把 Hugo 源码放进 blogsource 仓库。

如果远程仓库配错过

可以先删掉旧的：

git remote remove origin
git remote add origin https://github.com/yourusername/blogsource.git

提交并推送

git add .
git commit -m "Initial commit: Hugo project with theme"
git branch -M main
git push -u origin main

如果你是一个全新的空仓库，通常这样就够了，不一定非要 --force。

推送完成后，可以去 GitHub 上看一眼：

https://github.com/yourusername/blogsource

确认文件都已经上去了。

7. 先手动部署一次到公开仓库

如果你想先验证整套流程能跑通，可以先手动部署一遍。

先生成静态文件：

hugo --minify

然后进入 public/，把它作为一个单独仓库推到公开仓库：

cd public
git init
git add .
git commit -m "Deploy to GitHub Pages"
git remote add origin https://github.com/yourusername/yourusername.github.io.git
git branch -M main
git push -u origin main --force

这里之所以常见 --force，是因为 public/ 这个仓库本质上是生成产物，通常直接整体覆盖最省心。

8. 配置 GitHub Pages

去公开仓库 yourusername.github.io 里打开：

Settings -> Pages

然后确认：

Branch: main
Folder: / (root)

等一两分钟后，访问：

https://yourusername.github.io

如果网站已经能打开，说明最基本的部署链路已经通了。

9. 再做自动化部署

等你手动部署成功后，再上 GitHub Actions 会更稳。

目标是：以后你只需要把源码推到 blogsource，GitHub 就会自动构建并部署。

10. 生成 SSH 密钥

在 Git Bash 里运行：

ssh-keygen -t ed25519 -C "actions-deploy-key" -f ~/.ssh/gh-pages-key

生成后有两个文件：

私钥：~/.ssh/gh-pages-key
公钥：~/.ssh/gh-pages-key.pub

你可以分别查看：

cat ~/.ssh/gh-pages-key
cat ~/.ssh/gh-pages-key.pub

11. 把密钥配置到 GitHub

给公开仓库添加公钥

进入 yourusername.github.io 仓库：

Settings -> Deploy keys -> Add deploy key

然后填写：

Title: ACTIONS_DEPLOY_KEY
Key: 粘贴 gh-pages-key.pub 的内容
勾选 Allow write access

给源码仓库添加私钥

进入 blogsource 仓库：

Settings -> Secrets and variables -> Actions -> New repository secret

然后填写：

Name: ACTIONS_DEPLOY_KEY
Value: 粘贴 gh-pages-key 的完整内容

12. 添加 GitHub Actions 工作流

在项目里新建文件：

.github/workflows/deploy.yml

内容可以参考下面这份：

name: Deploy Hugo Site to GitHub Pages

on:
  push:
    branches: ["main"]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: true
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "0.145.0"
          extended: true

      - name: Build
        run: hugo --minify --gc

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: yourusername/yourusername.github.io
          publish_dir: ./public
          publish_branch: gh-pages
          keep_files: false

这里也记得把 yourusername 换成你自己的用户名。

13. 验证工作流是否生效

把工作流文件提交上去：

git add .github/workflows/deploy.yml
git commit -m "Add GitHub Actions workflow"
git push origin main

然后去 GitHub 的 Actions 页面看：

有没有出现新的 workflow
最新一次运行是不是绿色
如果失败了，点进去直接看日志

14. 后面写文章就会轻松很多

当自动化部署配好以后，后续更新博客基本就是这套流程：

在 content/ 里写或修改文章
本地预览确认没问题
提交源码
推送到 blogsource
等 GitHub 自动部署完成

命令大概就是：

git add .
git commit -m "Update blog content"
git push origin main

推上去之后，GitHub 会自动把静态页面部署到 yourusername.github.io。

最后补一句

如果你只是想先把博客跑起来，那就先完成下面这几步：

创建 Hugo 项目
加主题
本地预览
手动部署成功一次

等这条链路走通以后，再加自动化，心态会轻松很多，也更不容易被一堆 Git 和 Actions 报错劝退。

目录