Hugo stack主题建站（踩坑）指南

前言

经过三天的折腾，笔者终于搭好了博客的大体框架，期间遇到的小问题可谓数不胜数，网上搜索到的大部分教程都没办法适用于所有主题，而很多主题的文档也不完整。stack作为star数量最高的主题之一，具有相对比较完善的文档，但仍然需要与hugo官方文档相配合来搭建。在搭建过程中，给与笔者最大帮助的反而是GPT，可以通过GPT询问和补充文档细节，甚至帮你魔改主题，前提是必须严谨详细告诉他你的需求。因此笔者建议大家在搭建过程中与GPT/DeepSeek同步进度，可以帮助自己进一步了解hugo与所使用主题的结构。

注：笔者目前使用hugo + gitpages + Action自动化部署，会分享整个部署过程

环境准备

下载Hugo

笔者使用的是Windows系统，安装hugo使用了Windows下的chocolatey包管理器。

进入chocolatey官网下载页面，跟随官网的指引安装即可
安装后可以在命令行中输入choco --version检查是否安装成功
在命令行中使用chocolatey安装hugo：
- choco install hugo -confirm
- choco install hugo-extended -confirm（扩展版本，建议安装）
输入hugo version检查是否安装成功

注册和配置GitHub

关于GitHub注册和使用网上有很多教程，笔者不再赘述，贴一篇教程供大家参考：

GitHub配置教程

创建Hugo站点

新建Hugo根目录

Hugo创建新的站点非常简单，只需要在命令行中输入：

// 新建一个文件夹，包含hugo相关配置文件
hugo new site <YOUR-SITEFILE-NAME>

// 如果想要在当前目录下创建，请使用-f标识符
hugo new site . -f

Hugo站点目录结构

hugo站点目录结构如下所示（注：使用shitf + 鼠标滚轮可左右滚动）：

my-site/

├── archetypes/		<--存放生成文章时的模板

│   └── default.md	<--默认模板

├── assets/		<--包含通常通过资源管道传递的全局资源。包括图片、CSS、Sass、JavaScript 和 TypeScript 等

├── content/		<--组成站点内容的标记文件（通常是 markdown）和页面资源

├── data/		<--包含用于增强内容、配置、本地化和导航的数据文件（JSON、TOML、YAML 或 XML）

├── i18n/		<--包含多语言站点的翻译表

├── layouts/		<--包含将内容、数据和资源转换为完整网站的模板

├── static/		<--包含在构建站点时将复制到 public 目录的文件，例如 `favicon.ico`、`robots.txt`和用于验证站点拥有权的文件				

├── themes/		<--包含一个或多个主题，每个主题位于自己的子目录中

└── hugo.toml		<-- 站点配置

更多内容请访问Hugo官方文档

其中content/即博客文章.md文件存放的文件夹，要创建新的博客时，可直接在文件夹内创建，也可以在命令行中输入：

hugo new post_name/post.md

//建议每一篇博客都创建一个子文件夹`content/post_name/`，文件夹中存放博客的主体文件和图像文件等，方便整理和备份

这将在post_name文件夹中创建post.md文件，其中会包含一些archetypes/default.md的基本模板，如标题、描述、日期等。

要创建新的模板，可直接在archetypes文件夹中创建new_module.md文件，之后输入：

hugo new new_module/post.md

新生成的博客中就会使用新的模板。

选择和配置主题

选择主题

主题可以在Hugo官网中浏览，也可以在github中自行搜索寻找

配置主题

选好主题后，前往主题所在的仓库复制URL，使用git clone或git submodule add导入至本地hugo文件夹的themes目录下(submodule需要主题支持子模块管理，可查阅各主题的文档)

// 以我使用的stack主题为例
git clone https://github.com/CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack
// or
git submoruld add https://github.com/CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack

然后修改根目录下的配置文件config.toml/config.yaml/hugo.yaml（hugo不同版本可能有不同后缀，每种文件格式语法略微不同，我使用.yaml文件，若格式不同可直接将后缀修改为.yaml，或自行查阅其他格式的语法）

theme: 'hugo-theme-stack'	//注意名称要与主题文件夹相同

本地预览与配置

本地预览

主题导入成功后，可使用以下命令进行本地预览：

hugo server

运行成功后，命令行在最后输出如下内容：

Environment: “development”
Serving pages from disk
Running in Fast Render Mode. For full rebuilds on change: hugo server –disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)

进入http://localhost:1313/可以查看预览的网站界面

显示草稿

markdown的front matter中有draft字段，可以控制本篇内容是否为草稿，使用bool参数可以切换是/否草稿：

draft: true
draft: false

如果想在预览界面展示草稿，可以使用-D标识符

hugo server -D

配置主题

此时你的网页所展示的预览界面可能是空白，或者仅有少量与所选主题相关的元素，这是因为根目录下的配置文件没有内容。
在这一步，很多教程都会让你直接将主题文件夹目录下exampleSite中的所有内容复制粘贴至根目录下，而exampleSite是主题的一个Demo文件，其中包含了主题的配置信息、一些博客内容展示等等，博客中可能会包含一些无法解析/读取的内容，造成hugo编译错误，无法预览界面，因此笔者建议只复制主题目录下的配置文件，更好的是一边阅读Demo配置文件一边给自己的文件中增加内容，这样可以让自己熟悉配置文件中的参数，方便后期调整主题的样式。

部署博客至GitHub Pages

部署GitHub Pages

开始这一步之前请确保你已经注册了GitHub账号，下载了Git并配置完善。

首先使用hugo生成静态网站配置文件，进入你的博客文件根目录，打开命令行输入：

hugo

// 如果要将草稿也包括进来，可以使用-D标识符
hugo -D

这时hugo会在博客根目录下创建public/文件夹，储存生成的静态html文件。

在GitHub中创建仓库，仓库命名必须为<username>.github.io的格式，选择仓库为公开状态，随后先进入public/目录下，初始化git本地仓库，并将public中的文件push至仓库，仓库地址可在仓库主页code中直接复制URL，

// 在public目录下打开命令行，输入以下命令
git init -b main
git remote add origin YOUR-REPO-URL
git add .
git commit -m "输入你对本地提交的注释"
git push origin main

前往你的仓库页面，进入Settings–>Pages，source选择Deploy from a branch，branch选择main，点击save后等待部署完成，即可在<username>.github.io访问你的博客主页。

使用Action实现自动化部署

从上面的步骤可以看出，我们要发布新的博客时，必须进入public目录并推送，略微有些麻烦。可以使用Action功能实现自动化部署，只需要将本地源仓库推送至GitHub即可自动完成部署。

再此进入Settings–>Pages，将Deploy from a branch改为GitHub Action，新建一个仓库，此仓库可以随意命名并设置私有状态，用来存放博客根目录下所有文件。

将本地public目录下的.git文件夹删除，在博客根目录下重新初始化git仓库并绑定远程仓库(即你刚才创建的新仓库)。同时在根目录下创建文件夹.github/workflows，在文件夹中创建一个.yml文件，例如Deploy.yml，在文件中输入以下内容(注意注释中需要修改的部分)：

name: GitHub Pages

on:
  push:
    branches:
      - main  # Set a branch to deploy
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.145.0' # 注意修改成你的hugo版本，以防兼容性错误
          extended: true # 是否启用hugo extended

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          PERSONAL_TOKEN: ${{ secrets.ACTION_TOKEN }}
          PUBLISH_DIR: ./public 
          EXTERNAL_REPOSITORY: <username>/<username>.github.io # 你的Github Pages远程仓库名
          PUBLISH_BRANCH: main
          commit_message: auto deploy

此外也可以自行前往Hugo官网查阅相关文档。

随后将根目录下文件推送至你的GitHub仓库

git add .
git commit -m "提交注释"
git push origin main

进入GitHub仓库，可以看到Action部署过程，等待部署成功后，便可以使用<username>.github.io访问你的博客。

结语

至此，你已经初步完成了个人博客的搭建，关于主题的个性化设置，可以查阅各主题的文档，关于自定义域名的设置，可以参考这篇文章。另外，Hugo支持使用Markdown语法记录博客，关于Markdown的用法，可以查阅这份文档。

笔者在搭建博客过程中参考了以下文章：

Hugo搭建个人博客教程（GithubPages + 阿里云）

手把手学习 Hugo 博客的搭建:从入门到进阶

关于stack主题的魔改与美化，笔者主要依靠询问ChatGPT，以及参考了以下文章：

Hugo Stack 魔改美化

Hugo Stack主题装修笔记