静态网站Hugo + PaperMod主题 完整搭建指南

Hugo 是用 Go 写的静态网站生成器，PaperMod 则是它最火的多语言主题。
系统：Windows 10/11
目标：本地可预览、GitHub 可部署、国内可访问。
示例：https://www.imibtc.com/blog/

1 前期准备

1.1 安装 Git

1. 官网下载 git-scm.com → 双击安装

   • 一路 Next，到 Adjusting your PATH 时选第二项
   • 编辑器选 VS Code 或默认 Vim 都可以

2. 验证

   git --version   # 出现版本号即可

3. 设置用户名、邮箱

   git config --global user.name  "你的名字"
   git config --global user.email "you@example.com"

1.2 安装 Hugo（extended 版）

1. 打开 Hugo Releases
   下载 hugo_extended_*_windows-amd64.zip

2. 解压得到 hugo.exe，丢到

   D:\Hugo\bin

3. 把 D:\Hugo\bin 加入系统环境变量 Path

4. 验证

   hugo version   # 看到 extended 字样即可

2 创建站点

# 打开终端
cd /d D:\myblog          # 工作目录
hugo new site myblog     # 生成站点
cd myblog

目录结构：

myblog
├─ archetypes
├─ assets
├─ content
├─ data
├─ layouts
├─ static
├─ themes
└─ hugo.toml

3 安装 PaperMod 主题

3.1 下载

• 打开 hugo-PaperMod
  Code → Download ZIP → 解压
• 将文件夹改名为 PaperMod 并移动到 themes/

3.2 启用主题

编辑 hugo.toml（先给一份能跑起来的最小配置）：

baseURL = "https://你的域名/"
languageCode = "zh-cn"
title = "我的博客"
theme = "PaperMod"

[params]
  author = "你的名字"
  description = "记录技术与生活"

[menu]
[[menu.main]]
  name = "首页"
  url  = "/"
  weight = 10
[[menu.main]]
  name = "文章"
  url  = "/posts/"
  weight = 20
[[menu.main]]
  name = "关于"
  url  = "/about/"
  weight = 30

4 本地启动预览

hugo server

浏览器访问 http://localhost:1313/ 就能看到空白主题页。

5 创建第一篇内容

hugo new posts/hello-world.md

打开 content/posts/hello-world.md：

---
title: "Hello World"
date: 2025-07-26T12:00:00+08:00
draft: false
tags: ["demo"]
categories: ["随笔"]
---

## 你好，世界

这是我的第一篇文章。

保存后刷新浏览器，文章已经出现。

6 完善页面

6.1 关于页

hugo new about.md

content/about.md

---
title: "关于我"
showToc: false
---

- 职业：打工人
- 爱好：写代码、折腾博客
- 邮箱：you@example.com

6.2 归档页

hugo new archives.md

content/archives.md

---
title: "文章归档"
layout: "archives"
url: "/archives/"
---

7 添加评论系统（Giscus）

7.1 GitHub 侧操作

1. 新建公开仓库 my-blog-comments
2. Settings → Features → 开启 Discussions

7.2 Giscus 配置

打开 giscus.app/zh-CN：

• 填写仓库：你的用户名/my-blog-comments
• 页面 ↔ discussion 映射：pathname
• Discussion 分类：General

页面下方会给出一段配置参数，形如：

data-repo="xxx/xxx"
data-repo-id="R_xxx"
data-category="General"
data-category-id="DIC_xxx"

7.3 嵌入 Hugo

layouts/partials/comments.html

{{- if and site.Params.comments (not .Params.disableComments) }}
<script src="https://giscus.app/client.js"
        data-repo="你的用户名/my-blog-comments"
        data-repo-id="R_xxx"
        data-category="General"
        data-category-id="DIC_xxx"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        crossorigin="anonymous"
        async>
</script>
{{- end }}

在 hugo.toml 打开评论开关：

[params]
  comments = true

8 备案 + 运行时间 + 页脚

8.1 备案号（国内服务器必填）

[params.footer]
  text = '<a href="https://beian.miit.gov.cn/" target="_blank">粤ICP备12345678号</a>'

8.2 页脚模板（两行布局）

覆盖 layouts/partials/footer.html：

<footer class="footer">
  <!-- 第一行：版权、备案、技术 -->
  <div>
    &copy; {{ now.Year }} <a href="{{ .Site.BaseURL }}">{{ .Site.Title }}</a>
    · {{ .Site.Params.footer.text | safeHTML }}
    · Powered by <a href="https://gohugo.io" target="_blank">Hugo</a>
    & <a href="https://github.com/adityatelange/hugo-PaperMod" target="_blank">PaperMod</a>
  </div>

  <!-- 第二行：运行时间 -->
  <div style="margin-top:5px;font-size:13px;color:#666;">
    已运行 <span id="run-time">加载中…</span>
  </div>
</footer>

<script>
/* 把下面日期改成你的网站上线时间 */
const start = new Date('2025-07-20T00:00:00');
function fmt(n){ return n.toString().padStart(2,'0'); }
function update(){
  const diff = Date.now() - start;
  const d = Math.floor(diff/864e5);
  const h = fmt(Math.floor(diff/36e5)%24);
  const m = fmt(Math.floor(diff/6e4)%60);
  const s = fmt(Math.floor(diff/1e3)%60);
  document.getElementById('run-time').textContent = `${d} 天 ${h}:${m}:${s}`;
}
update();
setInterval(update,1000);
</script>

9 一键部署到 GitHub Pages

9.1 把站点推到 GitHub

# 在 myblog 目录
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/你的用户名/你的用户名.github.io.git
git push -u origin main

9.2 GitHub Actions 自动发布

.github/workflows/deploy.yml

name: Deploy Hugo

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
      with:
        submodules: true
    - uses: peaceiris/actions-hugo@v2
      with:
        hugo-version: 'latest'
        extended: true
    - name: Build
      run: hugo --minify
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./public

提交后，GitHub 会自动编译并把结果推送到 gh-pages 分支。
仓库 Settings → Pages → Source 选 gh-pages，几分钟后即可通过 https://你的用户名.github.io 访问。

10 常用命令速查

11 下一步可选

• 绑定个人域名：仓库 Settings → Pages → Custom domain
• 图片 CDN：把 static/images 扔到图床

• 文章自动摘要：在 hugo.toml 加

  [params]
    ShowToc = true
    ShowWordCount = true
    ShowReadingTime = true

至此，博客已完全可用。以后只需要在 content/posts/ 里写文章 → git push，GitHub 会自动更新。祝写作愉快！