使用 Hugo + Stack 搭建个人博客

Tue, 17 Jun 2025 15:59:02 +0800

什么是 Hugo

静态网站和动态网站

静态网站：网站完全由 HTML + CSS + Javascript 构成，不需要后端服务和数据库的参与。

动态网站：网站的内容需要后端服务进行渲染，页面的内容会根据用户以及存储在数据库中的数据进行动态渲染。

Hugo 介绍

Hugo 是最流行的静态网站生成器(Static Site Generator)之一，使用 Markdown 编辑网站的内容。它有着丰富的生态和主题，用户可以在社区中选择自己喜欢的主题，如果用户对现有主题不满意，允许用户进行自定义修改，得益于 Go 强大的模版功能，用户也可以轻松的从头开发一个属于自己的主题，但大部分人会选择使用现有的主题，并按照需要在已有的主题上进行自定义的修改。

Hugo 配置文件

hugo 的配置文件名为 hugo.toml。hugo 支持将配置全部放入到 hugo.toml 文件中，也支持将配置文件的内容进行拆分到不同的配置文件中。将配置文件的内容进行拆分时，配置文件必须时在 config/_default/ 目录下，并且文件名必须是 root key，下面的两个配置是等价的：

config/_default/hugo.toml

[params]
  foo = 'bar'

config/_default/params.toml

foo = 'bar'

Hugo 基于环境进行配置

Hugo 支持根据环境对参数配置不同的值，hugo 默认设置了两个环境：

production：使用 hugo 命令时，激活的就是 production 环境。production 环境的配置放在 config/production/ 目录下
development: 使用 hugo server 命令时，激活的就是 development 环境。development 环境的配置放在 config/development/ 目录下
自定义环境：使用 hugo server -e <env_name> 时，激活的就是 env_name 环境。env_name 环境的配置放在 config/<env_name>/ 目录下

Hugo 内容模板

使用 hugo new content <archetype_name>/<page_name> 命令创建一篇文章时，内容模板查找的顺序如下：

在项目根目录下的 archetypes 目录下寻找是否存在 archetype_name 的文件夹或者是 archetype_name.md 的文件
没有的话则查找名为 default 的文件夹或者是 default.md 的文件
如果项目的根目录下不存在，则查找配置的主题中的 archetypes 文件夹是否存在 archetype_name 的文件夹或者文件

下面通过实际的例子来说明情况：

查找文件情况：

hugo new content post/test.md

查找 archetype 的顺序如下：

archetypes/post.md
archetypes/default.md
主题下的 archetypes/post.md
主题下的 archetypes/default.md

如果管理页面的方式是 page bundle，新建内容时，查找的就是 archetypes 目录下同名的文件夹, 例如：

hugo new content post/test

查找 archetype 的顺序如下：

archetypes/post/
archetypes/default/
主题下的 archtypes/post/
主题下的 archtype/default/

Stack 主题

自定义样式

Stack 主题允许用户自定义修改样式，操作步骤如下：

在博客界面按下 F12 打开开发者工具
使用开发者工具提供的元素选择器定位到相关的元素
调整相关的样式，调整完后，将选择器及其所属的样式全部放入到 assets/scss/custom.scss 文件中

自定义博客布局

Stack 的布局或者 Icon 等不符合你的要求，这个时候可以借助开发者 + 全局搜索的方式来定位代码的位置，然后进行修改。步骤如下：

打开开发者工具，使用开发者工具提供的元素选择器定位需要修改的元素
将元素中区分度比较大的标识复制下来，这样能够快速的定位元素在 Stack 源码中所处的文件。比如元素的 ID，元素 class 中区分度比较高的 class，或者整个 class 复制下来等等。
在 Stack 源码中全局搜索复制下来的标识，定位元素在 Stack 源码中的哪个文件中
假设定位到的路径是：layouts/a/b/c/d.html，如果需要修改样式，就需要在博客的目录也存在 layouts/a/b/c/d.html 文件。将 Stack 源码中 d.html 文件的内容复制一份到博客目录的 d.html 文件中，最后修改博客目录中的 d.html 即可。

上图中圈出来的图标我不是非常的喜欢，接下来使用图文的方式展示如何去除掉对应的图标

使用开发者工具定位到图标所在的元素

选择一个区分度比较高的标识符复制下来，这里我选择 class="widget-icon"
在 Stack 主题的源码中去搜索 class="widget-icon"

从上图中可以看到，全局搜索一共找到了四个文件，挨个查看文件的内容可以确定图标的源码在 archives.html 文件。

archives.html 文件的路径：layouts/partials/widget/archives.html。将该文件的目录结构复制一份到博客所在的目录，并将 archives.html 文件复制到博客中，然后修改博客中 layouts/partials/widget/archives.html 文件:

查看效果：

自定义 SVG 图标

在 iconfont 选择自己心仪的图标，选择图标时，一定要手动指定一个颜色

复制 SVG 代码，并保存在一个文件中，比如 github.svg 文件中

将 github.svg 在编辑器中打开，并将 fill 字段的值改成 currentColor

将 github.svg 放入到 assets/icons/ 目录下

将网站托管到 Nginx

hugo 编译之后，会在项目的根目录下生成一个 public 目录。public 目录下的文件就是静态页面包含的所有资源，其中的 index.html 是静态页面的入口。

如果没有服务器，则可以将生成的页面托管到 Github Page, Netlify, Vercel 等服务商中。如果有服务器，则可以将生成的静态页面交给 Nginx 处理。

把静态页面交给 Nginx 处理，只需要把 public 目录下所有的文件放入到 nginx 所在的服务器上。

假设将 public 目录下的所有文件都放在了 /var/www/hugo/ 目录下，nginx 配置文件 /etc/nginx/nginx.conf 修改后的内容如下：

user www-data;
worker_processes auto;
pid /run/nginx.pid;
error_log /var/log/nginx/error.log;
include /etc/nginx/modules-enabled/*.conf;

events {
        worker_connections 768;
}

http {
        sendfile on;
        tcp_nopush on;
        types_hash_max_size 2048;
        include /etc/nginx/mime.types;
        default_type application/octet-stream;

        ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3; # Dropping SSLv3, ref: POODLE
        ssl_prefer_server_ciphers on;
        access_log /var/log/nginx/access.log;
        gzip on;
        include /etc/nginx/conf.d/*.conf;
        include /etc/nginx/sites-enabled/*;
        
        server {
            listen 80;  # 监听80端口
            server_name hugo.local.com;  # 替换为你的域名，这是个可选配置项, 配置后就可以使用 http://hugo.local.com 访问

            root /var/www/hugo;  # 设置网站的根目录为 /var/www/hugo 文件夹
            index index.html;  # 网站的入口文件

            location / {
                try_files $uri $uri/ =404;  # 尝试找到请求的文件
            }

            # 处理静态文件
            location ~* \.(css|js|jpg|jpeg|png|gif|ico|svg|woff|woff2|ttf)$ {
                expires 30d;  # 设置缓存时间
                access_log off;  # 关闭访问日志
            }

            # 错误页面
            error_page 404 /404.html;  # 自定义404页面
        }
}

需要注意的是 /var/www/hugo/ 目录的权限，目录的权限需要与 /etc/nginx/nginx.conf 中的 user 参数一致，比如上述配置文件中的配置为: user www-data，那需要使用如下的命令修改目录权限：

chown -R www-data:www-data /var/www/hugo

Hugo on FelixHao's Blog