0002 - Hugo博客搭建完整记录：从0到1的踩坑之旅

前言

本文记录了从零开始搭建 Hugo 博客的完整过程，包括所有的疑问、踩过的坑以及解决方案。希望这篇笔记能帮助到想要搭建个人博客的朋友。

一、初始需求与疑问

1.1 关于 hugo.toml 配置的疑问

问题：左侧代码什么意思？

baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'

解答：

• baseURL：网站的基础 URL，部署时需要改为实际域名
• languageCode：网站语言代码，en-us 表示美式英语
• title：网站标题，显示在浏览器标签和页眉

1.2 GitHub Pages 域名配置

问题：如何知道我的 GitHub 域名？直接替换就能用吗？

解答：

• GitHub 用户名是 Wubajie，所以域名是 https://wubajie.github.io/
• 不能直接替换，还需要：
  1. 创建名为 wubajie.github.io 的仓库
  2. 构建网站并推送到 GitHub
  3. 启用 GitHub Pages

二、搭建过程中的问题与解决

2.1 网站 404 问题

问题：为什么我的网站是 404？

原因：GitHub Pages 需要构建后的静态文件，而不是源代码。

解决方案：

1. 本地运行 hugo 命令构建网站
2. 将 public 目录的内容推送到 GitHub
3. 或者使用 GitHub Actions 自动构建

2.2 域名跳转问题

问题：配置了 wuqq547.com 域名后，网站总是跳转到这个域名，但这个域名还没购买。

解决方案：

1. 在 GitHub Pages 设置中删除 Custom domain
2. 将 hugo.toml 中的 baseURL 改回 https://wubajie.github.io/
3. 删除 static/CNAME 文件
4. 重新构建并推送

2.3 数学公式渲染问题

问题：网页无法正确渲染数学公式。

解决方案：

1. 创建 layouts/partials/extend_head.html 文件
2. 添加 MathJax 3 支持：

{{ if or .Params.math .Site.Params.math }}
<script>
  MathJax = {
    tex: {
      inlineMath: [['$', '$'], ['\\(', '\\)']],
      displayMath: [['$$', '$$'], ['\\[', '\\]']]
    }
  };
</script>
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
{{ end }}

3. 在文章头部添加 math: true

2.4 主页摘要显示问题

问题：主页显示文章摘要，但摘要中的数学公式无法渲染。

解决方案：

1. 在文章头部添加 hideSummary: true
2. 这样主页只显示标题和时间，不显示摘要

三、发布博客的完整流程

3.1 创建新文章

# 方法1：使用 Hugo 命令
hugo new posts/文章标题.md

# 方法2：手动创建文件
# 在 content/posts/ 目录下创建 .md 文件

3.2 文章模板格式

---
title: "文章标题"
date: 2026-03-07
draft: false
math: true          # 启用数学公式
hideSummary: true   # 隐藏主页摘要
tags: ["标签1", "标签2"]
categories: ["分类"]
---

## 正文内容

支持 Markdown 语法和数学公式：$E = mc^2$

3.3 构建并部署

# 1. 构建网站
hugo

# 2. 进入 public 目录
cd public

# 3. 提交并推送
git add .
git commit -m "添加新文章"
git push origin main

四、重要配置总结

4.1 hugo.toml 配置

baseURL = 'https://wubajie.github.io/'
languageCode = 'zh-cn'
title = '我的技术博客'
theme = 'PaperMod'

[params]
[params.homeInfoParams]
Title = "Hi there 👋"
Content = "Welcome to my blog"

4.2 文件结构

my-tech-blog/
├── content/
│   └── posts/
│       ├── 0001-矩阵方程与向量化最小二乘.md
│       └── 0002-Hugo博客搭建完整记录.md
├── layouts/
│   └── partials/
│       └── extend_head.html    # MathJax 配置
├── static/
├── themes/
│   └── PaperMod/
└── hugo.toml

五、踩坑记录

六、后续计划

1. 购买自定义域名 wuqq547.com 并绑定
2. 优化博客主题样式
3. 添加评论功能
4. 添加网站访问统计
5. 持续更新技术笔记

七、参考链接

• 博客地址：https://wubajie.github.io/
• Hugo 官方文档：https://gohugo.io/
• PaperMod 主题：https://github.com/adityatelange/hugo-PaperMod
• GitHub Pages：https://pages.github.com/

结语

搭建博客的过程虽然遇到了不少问题，但每解决一个问题都是一次学习。希望这篇笔记能帮助到更多人，也欢迎访问我的博客交流讨论！