Featured image of post 使用Hugo搭建静态博客
计算机 应用

使用Hugo搭建静态博客

前言

博主原本使用WordPress+Inspire搭建个人博客，然而，Inspire不再更新，也不再兼容新版php，兼容性逐渐出现各种问题；与此同时，博主不太喜欢wordpress默认的一系列主题，为改善博客兼容性问题，提高博客相应速度，博主决定从wordpress的动态博客转向纯Html的静态博客。经过筛选，博主最终决定使用**Hugo框架+Stack主题**搭建我的静态博客。

需要注意的是，Hugo与WordPress是不同的，Hugo采用MarkDown作为文本格式，在写好内容后，使用Hugo作为生成工具，手动生成Html等静态资源，Hugo没有专门的内容编辑后台，所有文字工作需要在本地完成。

1.下载Hugo

由于博主本地使用Windows环境，故下载Windows版本的Hugo。Hugo分为3个版本，具体区别如下表

版本 特点 SCSS/SASS 支持 Hugo Pipes 支持 hugo deploy 支持
Standard（普通版） 最基础版本，适合纯 Markdown 转 HTML ❌ ❌ ❌
Extended（拓展版） 支持现代前端构建，适合大多数主题 ✅ ✅ ❌
Extended with Deploy 在 Extended 基础上增加部署功能 ✅ ✅ ✅

🔑 关键区别

  1. 普通版 (Standard)

    • 适合纯 Markdown → HTML 的轻量级博客或文档站点

    • 没有复杂前端需求时足够

    • 不支持 SCSS/SASS、PostCSS、Tailwind 等

  2. Extended (拓展版)

    • 支持 SCSS/SASS 编译（Hugo Pipes）

    • 支持 PostCSS，能直接处理 Tailwind、Autoprefixer 等

    • 适合大多数现代 Hugo 主题（因为很多主题依赖 SCSS/SASS）

  3. Extended with Deploy

    • 在 Extended 的基础上，额外支持 hugo deploy 命令

    • 可以直接把生成的网站部署到远程（如 S3、Azure、GCP 等）

    • 适合需要 Hugo 自带部署功能的用户，否则和 Extended 没区别

为了后期使用的便利，直接下载 hugo_extended_withdeploy 就完事了

下载完成后，你会得到一个Hugo静态网站生成器的exe执行文件，该执行文件可以帮助你生成一个静态网站的全部内容。此步骤可做可不做：将hugo所在的目录放在系统环境变量path中。笔者是做了这一步的，这一步的作用是，无论你在那个目录下，都能使用hugo命令。如不添加，则当你生成了一个静态网站资源，你需要将hugo.exe文件拖入静态网站资源的目录下，以便你日后在在目录内调用hugo命令。

在控制台（如果没有添加环境变量，则需要在有hugo.exe的目录下执行）使用hugo version命令测试hugo是否安装成功，如果安装成功，则输出如下

1
2

D:\Web\blog>hugo version
hugo v0.150.1-ce44a8e835e6934292acda936e5b43b70f451af9+extended+withdeploy windows/amd64 BuildDate=2025-09-25T10:26:04Z VendorInfo=gohugoio

2.创建新站点

在cmd中（如果没有配置全局路径，在hugo.exe目录下使用该命令）使用命令，会在当前目录下创建一个站点

1

hugo new site yoursitename #yoursitename 是你的站点文件夹名称， 可以使用dev或自己起个名字

上面截图显示了创建新的站点成功，并且会给你一些提示，按照提示走就可以花很少的时间搭建出一个静态网站

Hugo会在这个D:\Web目录下自动新建一个名为Test的目录，如上图所示

进入test目录

1
2
3

D:\Web\blog>cd D:\Web

D:\Web>

3.添加主题

Hugo下载好后，就可以开始挑选自己喜欢的主题，可以在Hugo官网下挑选（Complete List | Hugo Themes），每个主题都可以点进去查看详细信息与下载地址，笔者这里使用了stack主题，特别适合用于搭建个人博客网站。可以通过Hugo Themes中选中stack主题，进去Download，也可以在GitHub上直接搜索CaiJimmy/hugo-theme-stack: Card-style Hugo theme designed for bloggers，仿照上面下载hugo的方法找到对应位置下载源码（source code）压缩包即可。

3.1解压主题

将stack主题的源码解压到test\themes目录下（接下来为了方便，test统称为站点目录）。

将解压的目录名称中的版本号删除，改成像我一样hugo-theme-stack

值得注意的是，如果你想换其它主题，或者你一开始便不打算下载stack主题，操作也是一样的，同样将版本号删除，并将yaml配置文件中的主题改成对应的主题目录名称即可（后面会提及）

3.2从主题文件中复制两个重要文件

在解压的目录（hugo-theme-stack）下，有一个样例目录名为：exampleSite，里面有两个非常重要的东西，一个是content目录，一个是hugo.yaml配置文件，将这两个文件复制出来

放到站点目录下

将原本的默认配置文件hugo.toml删除，用我们复制过来的hugo.yaml做配置文件

注意：在content\post\目录下，有一个rich-content的目录删掉，post目录下存放的就是你的博客内容，这个rich-content博客中做了一些引用Youtube的样例操作，可能会导致你运行失败，这些国外网站可能会导致你访问超时

4.修改配置文件

打开刚才复制过来的hugo.yaml

4.1更换主题

可以看到，这里主题选择的是hugo-theme-stack，如果你想更换其它的主题，只需下载其它主题的源码到themes\目录下，并将配置文件中的主题换掉即可

以下使用代码段形式展现笔者修改了的部分:

笔者将url的重定向到自己的博客域名

1

baseurl: https://blog.octlog.com

修改了著作权，当然，这个著作权是指本博客的著作权，而非hugo也非该主题

1

copyright: 八爪日志

将默认语言修改为中文

1

DefaultContentLanguage: zh-cn

修改以下配置，据说可以更精确的计算读文章的时长

1

hasCJKLanguage: true

这里修改的是博客左上方的标题，有中英两个版本，但笔者的博客全是中文博客，还没有做国际化的打算，故只修改了中文部分

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

languages:
    en:
        languageName: English
        title: Example Site
        weight: 1
        params:
            sidebar:
                subtitle: Example description
    zh-cn:
        languageName: 中文
        title: 八爪日志
        weight: 2
        params:
            sidebar:
                subtitle: 一个科技爱好者的博客

这个参数是指一页展示多少篇文章

1
2

pagination:
    pagerSize: 5

你可以在static目录下存放你博客的图标，将名称改为favicon.ico

1
2

favicon: /favicon.ico 
    # e.g.: favicon placed in `static/favicon.ico` of your site folder, then set this field to `/favicon.ico` (`/` is necessary)

以下参数是修改你的头像以及添加emoji（头像右下角的表情），首先将图片名称改为avatar.png，并添加到assets\img\目录下，如果没有img目录可自行创建，然后将参数修改：

1
2
3
4
5
6
7

sidebar:
        emoji: 😺
        subtitle: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
        avatar:
            enabled: true
            local: true
            src: img/avatar.jpg

修改下面的参数，可以添加或修改头像下面的快捷链接小图标，笔者增加了链接进入笔者B站主页和进入笔者CSDN主页的快捷链接，图标以SVG格式存放在assets\icons\目录下，值得注意的是，下面参数icon是图标的文件名去掉.svg，比如brand-bilibili.svg去掉.svg，如下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

social:
        - identifier: github
          name: GitHub
          url: https://github.com/572615681
          params:
              icon: brand-github
      
        - identifier: home
          name: Home
          url: https://www.octlog.com
          params:
              icon: navigation
        
        - identifier: csdn
          name: CSDN
          url: https://blog.csdn.net/chenxiyu712
          params:
              icon: brand-coinbase
              
        - identifier: mvs
          name: MVS
          url: https://msdn.octlog.com
          params:
              icon: brand-visual-studio

说明，本文的icon图标来源于此网站，此网站的icon风格与此主题较为匹配

5.运行博客

命令：

1

hugo server -D

注意： 必须是在站点目录下使用该命令。（上面我们通过cd test进入了目录） 必须是D而不是d

运行命令后会出现以下信息

可以看见，通过访问http://localhost:1313即可访问博客

6.开始写文章

6.1文章目录结构

首先看一下文章目录结构，文章都保存在content目录下：

看看对应的网站结构：

其实无论是page，categories，post，都可以看作一个一级目录，然后每一篇文章，每一个分类，亦或者每一个侧边栏的选项，都是二级目录，二级目录下才是真正的内容，比如，在categories目录下：

有这么几个二级目录，分别代表了四个我已经创建并附带说明的分类

7.如何写文章

写博文采用的是markdown格式，使用Typora工具，写markdown手感特别好。

在写博文的时候需要注意的是开头携带的信息，如下所示：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

+++
title = '爱快+OpenWRT最佳部署方案探讨'
date = 2025-08-18T21:55:00+08:00
slug= "ikuai&openwrt-policy-routing"
image = "https://oss.octlog.net/ikuai%26openwrt-policy-routing/top.webp"
categories = [
"计算机",
"网络",
]
tags = [
"iKuai",
"OpenWrt",
"Linux",
]

+++

如果是普通的编写模式，则是下面这个样子的：

1
2
3
4
5
6
7
8

title：文章标题
description：副标题，简介
date：编写日期
image：文章最上方的图片
categories：分类
tags：标签
分类和标签的内容可以是中文，可以多个，但需要采用[“xx”,“xx”]的格式
:后需要加一个空格，再输入内容

后面的就按照正常markdown创作即可

© 2020 - 2025 八爪日志
使用 Hugo 构建
主题 Stack 由 Jimmy 设计