如果你在静态博客这条路上泡过一段时间大概率会经历这样一个循环先被Hexo的主题数量吸引后来觉得Node.js构建慢、插件多了容易出幺蛾子转头试WordPress功能是真全但维护一个数据库和PHP环境又有点重再往后可能自己动手用React搓过一个博客技术上是爽了内容却迟迟没写几篇。我最终把技术博客稳定跑起来是在换成Hugo加Stack主题之后。Hugo的构建速度几乎是瞬时的Stack这个主题又恰好踩在“极简”和“够用”的平衡点上。这篇文章不是主题作者的官方文档复述而是我反复搭建、改版、部署之后的一份完整沉淀重点讲清楚三件必改的配置以及五个能让站点从“默认模板”变成“个人作品”的美化技巧。无论你是第一次接触Hugo还是已经搭过但觉得哪里不对劲都可以把它当作一份可以直接照做的操作手册。1. 为什么是Stack极简技术博客的主题选型逻辑1.1 “极简”不是简陋而是一种克制很多人第一次看到Stack的默认效果会觉得它不够惊艳没有花哨的动态背景没有复杂的侧边栏动画甚至首屏看起来就是文章卡片列表。但这种“第一眼平淡”恰恰是它最值钱的地方。Stack的设计核心是内容优先。它把所有干扰阅读的视觉元素压缩到最低用清晰的卡片结构、适度的留白和统一的字体层级让读者进入站点后第一时间看到的是文章本身而不是主题的炫技。这种体验对技术博客尤其重要——来看你博客的人绝大多数是想解决问题、读技术总结不是来欣赏网页特效的。另一个容易被忽视的点是Stack对Markdown原生写作的支持非常友好。你在本地用VS Code或任何编辑器写Markdown命令行执行hugo new post/xxx/index.md专注写作本身不需要像某些博客系统那样在网页后台里调整排版。发布、修改、分类、标签全部可以用文本文件管理配合Git做版本控制这种工作流对程序员来说几乎是天然的。1.2 对比几个常见主题选型时踩过的坑如果说选Hugo是因为构建速度和内容管理方式那在主题选择上我并不是一开始就认准Stack的。为了让你少走弯路我把几个常用主题的取舍列出来主题设计取向配置复杂度搜索/评论能力适合场景Stack卡片式极简排版克制中低结构清晰原生支持搜索评论需外接技术博客、个人知识库PaperMod轻量灵活偏文档风格低单配置搞定大半搜索需自己接入极简个人站、文档站LoveIt/DoIt功能丰富组件多高参数很多开箱即用功能全不想折腾、追求开箱即用Hugo默认主题整洁但偏向示例低基础能力有限临时页面、学习用我一开始用的是LoveIt系列功能确实多但随之而来的是配置文件里大量用不到的参数以及每次主题升级都要检查哪些自定义布局被覆盖。换到Stack之后最大的感受是它的覆盖机制简单你不需要改主题源码只需要在自己的layouts目录里放同名模板文件Hugo会优先使用你的文件。这个机制让我敢放手去定制因为它把“自定义”和“主题升级”两者解耦了。2. 从零跑起来环境安装与主题初始化2.1 安装Hugo与创建站点骨架Stack主题依赖SCSS编译因此一定要安装Hugo的extended版本否则本地预览时会报错。macOS用户直接用Homebrew安装brew install hugoWindows用户我推荐用Scoopscoop install hugo-extended如果用的是Linux最好从Hugo官方GitHub Release页面下载extended版本的二进制而不是依赖apt仓库里可能过时的版本。确认安装成功hugo version看到输出里有extended字样就说明版本没问题。接着创建站点hugo new site my-blog cd my-blog git init这里建议先git init因为后面拉取主题时如果用git submodule方式必须在一个Git仓库里操作。2.2 拉取Stack主题与核心目录结构Stack主题的Git仓库是github.com/CaiJimmy/hugo-theme-stack推荐用submodule方式引入git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack使用submodule而不是直接把主题文件夹复制进来原因很简单将来想要升级主题只需要一条git submodule update --remote命令而且你做的所有自定义内容都在主题目录之外不会因为升级被覆盖。Stack主题自带一份完整的示例站点位于themes/hugo-theme-stack/exampleSite。第一次使用时建议直接把示例内容复制到站点根目录cp -r themes/hugo-theme-stack/exampleSite/* .这样你会得到一个可以直接运行的站点里面有主题作者写好的示例文章和完整的配置文件。然后启动本地预览hugo server -D在浏览器里打开http://localhost:1313一个纯正的Stack站点已经跑起来了。这里要提醒一句不同版本的Stack主题示例目录里可能用的是content/post也可能用content/posts这都不重要关键是你的mainSections配置要和实际目录一致后面我会在必改配置里专门讲。3. 3个必改配置站点身份、内容流与阅读体验3.1 第一改站点身份、信息描述与导航菜单刚复制的示例站点里满屏都是作者的示例内容。你首先要做的是把站点最基础的“身份信息”全部换成自己的。在Hugo根目录打开配置文件。新版Hugo默认使用hugo.tomlStack示例里也可能是hugo.yaml语法不同但字段含义一致这里以hugo.toml为例baseURL https://blog.example.com/ title 海风的技术笔记本 languageCode zh-cn theme hugo-theme-stack paginate 10title会成为站点标题languageCode zh-cn会影响RSS、HTML标签的lang属性对中文SEO有直接影响别漏掉。baseURL先填你准备部署的域名即使本地预览用不到生成最终的站点地图和RSS时也会依赖它。然后配置主导航菜单[[menu.main]] name 首页 pageRef / weight 1 [[menu.main]] name 文章 pageRef /post weight 2 [[menu.main]] name 归档 pageRef /archives weight 3 [[menu.main]] name 关于 pageRef /about weight 4weight决定菜单顺序从小到大排列。此处pageRef要根据你实际的内容目录调整如果目录是posts就写/posts。最后补上作者信息。Stack新版配置中侧边栏信息通常放在[params.sidebar]下[params.sidebar] avatar /img/avatar.webp description 写代码、读paper、偶尔折腾工具链同时可以在[params]中设置站点描述[params] description 一个关注云原生与前端工程化的个人博客这组配置是整个站点的地基。哪怕你后面什么都不美化把这套信息改对站点就已经从“演示项目”变成了“我的博客”。3.2 第二改首页内容流、摘要规则与分类标签体系第二个必改项决定你首页到底展示什么。Stack默认会把站点里的所有页面都当成文章流来展示如果你之后创建了“关于”页面或独立页面它们很可能也会混进首页列表里。解决办法是设置mainSections明确告诉Hugo只有哪个目录下的内容算真正的文章。[params] mainSections [post]如果你的文章放在content/posts目录就写成[posts]。这个值建议用数组形式万一你以后想增加“周刊”目录可以改成[post, weekly]。然后是每页文章数paginate 10表示每页展示10篇。这个数值我实测下来比较合适首屏加载不会太长翻页频率也合理10到15都可以但别设成5以下不然读者翻页太频繁。Stack的列表卡片会优先读取文章front matter里的description字段作为摘要。默认情况下如果这个字段为空Hugo会自动取正文前几十个字。问题在于自动截断的句子经常不完整甚至会把一个代码块从中间切断。所以我的约定是每篇文章的front matter里必须写description一句话说清这篇文章在讲什么。一个标准的技术文章front matter大概长这样title 如何用Hugo Stack主题打造极简技术博客 description 从环境安装到主题美化覆盖Stack主题3个必改配置和5个高级美化技巧 date 2025-03-01T10:00:0008:00 lastmod 2025-03-05T18:00:0008:00 image cover.webp tags [Hugo, Stack, 博客] categories [工具链] draft false这里我特意加了lastmod字段Hugo会自动把lastmod更新的时间写入页面对搜索引擎的抓取判断有帮助也方便你自己回头查看文章是否过期。3.3 第三改代码高亮、评论开关与阅读参数技术博客绕不开代码展示第三个必改项就是代码高亮和评论区。Hugo默认使用内置的Chroma做代码高亮需要配置一下才能拿到最好的效果[markup.highlight] noClasses false lineNos true lineNumbersInTable false style github-dark几个关键点说明一下noClasses false表示Chroma输出CSS类名而不是内联样式这样才能配合Stack主题的暗色/亮色模式自动切换高亮配色。lineNos true开启行号对技术文章读者定位代码位置很有帮助。lineNumbersInTable false非常重要。如果设置成true复制代码时行号可能会被一起带进剪贴板很烦人。然后处理评论。Stack本身不内置评论服务需要外接。如果你还没想好用哪家先在配置里把评论功能关掉[params.comments] enabled false等后面读到第四部分的giscus接入方案再回来把enabled改成true。阅读参数方面Stack部分版本支持在[params.article]下控制阅读时间、版权提示等显示选项。不同版本字段名有差异建议直接查看你下载的themes/hugo-theme-stack/exampleSite里的配置文件里面注释项非常全按需打开即可。我的建议是打开阅读时间显示让读者进来自动评估这篇文章大概需要几分钟体验更友好。到这里三个必改配置就齐了。它们分别对应三个问题访客知不知道这是谁的站、首页展示哪些内容、代码和评论体验是否合格。做完这三步博客已经能正常对外见人了剩下的美化是锦上添花。4. 5个高级美化技巧从能用变成耐看4.1 技巧一用CSS变量换掉模板气质Stack默认的蓝色系其实很耐看但如果你想让它变成自己的风格最优雅的方式是覆盖CSS变量而不是去改主题源码。Stack把大部分颜色、圆角、间距都定义成CSS变量你只需要创建一个自定义CSS文件然后让主题加载它。在assets/css/custom.css中写入:root { --body-background: #f7f7f8; --card-background: #ffffff; --card-text-color-main: #1f2328; --accent-color: #e65100; --card-border-radius: 12px; --section-padding: 24px; } [data-color-schemedark] { --body-background: #161618; --card-background: #202024; --card-text-color-main: #e6e6eb; }然后告诉Stack加载这个文件。在hugo.toml的[params]下添加[params] customCSS [css/custom.css]CSS变量名在不同版本里可能有差异最靠谱的方式是去主题源码里搜--card-background看它当前定义了哪些变量。我实测下来上面的几个变量在大多数版本都是存在的。我自己把强调色从默认蓝换成了一种偏暖的橙色整体观感一下子从“程序员模板”变成了“有个人品牌的工作室”。4.2 技巧二自定义Widget把首页变成个人门户Stack原生支持widget机制默认有搜索、最近文章、分类、标签云等。但它允许你注册一个自定义widget这就有意思了——你可以在首页侧边栏塞进任何你觉得重要的内容。在layouts/partials/widget/custom.html中创建一个个人简介卡片aside classwidget div classwidget-title关于我/div div classcustom-widget-content img src/img/avatar.webp altavatar loadinglazy / p主要写Go、Kubernetes偶尔聊前端工程化。/p a href/about完整介绍 →/a /div /aside然后在配置文件中启用这个widget[params] widgets [search, recent, categories, tag-cloud, custom]这里的关键是这个custom字符串Stack会去layouts/partials/widget/custom.html找对应的模板。如果你的文件命名不同这里也要对应改。我实际用这个机制在侧边栏放了自己的GitHub和公众号入口还在底部加了一个“最近在学什么”的小模块。这个位置比固定写在每篇文章里的签名更醒目也不会干扰正文阅读。4.3 技巧三给代码块加复制按钮和终端符号技术博客里读者复制代码的频率很高。虽然浏览器自带复制功能但选中一大段代码再右键复制体验终究不够顺畅。给代码块加一个浮动“复制”按钮能明显提升实用感。在assets/js/custom.js中写入document.querySelectorAll(.post-content .highlight).forEach((block) { const btn document.createElement(button); btn.className copy-code-btn; btn.textContent 复制; btn.addEventListener(click, async () { const code block.querySelector(code).innerText; await navigator.clipboard.writeText(code); btn.textContent 已复制; setTimeout(() (btn.textContent 复制), 2000); }); block.style.position relative; block.appendChild(btn); });再用CSS把按钮放到代码块右上角.copy-code-btn { position: absolute; top: 8px; right: 8px; z-index: 2; border: none; background: rgba(128, 128, 128, 0.2); color: inherit; font-size: 12px; padding: 4px 10px; border-radius: 6px; cursor: pointer; opacity: 0; transition: opacity 0.2s; } .highlight:hover .copy-code-btn { opacity: 1; }这里有个细节值得注意只有鼠标悬停在代码块上时才显示按钮否则每段代码右上角都挂着一个按钮阅读时反而觉得杂乱。这个方法不依赖任何第三方库纯原生JavaScript搞定长期维护成本几乎为零。4.4 技巧四用Giscus接入评论系统和GitHub Discussion打通我最后选定的评论方案是Giscus它的原理是让评论内容存储在GitHub仓库的Discussion中。好处显而易见评论数据不会流失不需要维护额外的数据库而且读者可以直接用GitHub账号登录评论对技术博客的访客来说门槛很低。接入步骤不复杂。先在GitHub上创建一个公开仓库并开启Discussions功能然后安装Giscus应用在giscus.app上按提示选择仓库它会自动生成一段嵌入代码。然后在自己的站点里创建一个短代码layouts/shortcodes/giscus.htmldiv classgiscus/div script srchttps://giscus.app/client.js >{{ giscus }}之后执行hugo new post/xxx/index.md新文章会自动带上评论短代码。我在实际使用中遇到的唯一问题是首次加载时Giscus脚本需要从外域拉取国内访问偶尔偏慢但考虑到评论数据完全由自己掌控这一点取舍是值得的。4.5 技巧五统一文章封面图让列表不再杂乱极简主题最怕的不是功能少而是内容封面忽大忽小、忽有忽无。Stack的列表卡片会根据文章的image字段决定是否显示封面如果一部分文章有图、一部分没有首页会显得很零散。因此我强烈建议把封面图纳入写作流程而不是“有空就配一张”。具体做法是给每篇文章的front matter固定加上image /img/post/2025/03/hugo-stack-guide.webp图片统一放static/img/post目录下按年份、月份建子目录避免图片堆积后找起来困难。尺寸方面列表卡片实际展示比例接近16比10我统一用1200x750导出WebP格式单张控制在200KB以内。这个尺寸同时能满足大部分社交平台分享时的缩略图需求一举两得。如果你想让Hugo在构建时自动处理图片压缩可以在配置中加入[imaging] resampleFilter Lanczos quality 80但要注意这个配置只对Hugo的resources图片处理流程生效放在static目录里的原始图片不会自动压缩。更稳妥的做法还是写进本地工作流每次写完文章顺手用图片工具导出一次WebP。封面图统一之后首页的视觉整齐度会立刻提升一个档次。这不是什么魔法技巧但恰恰是“极简风格”下最容易拉开差距的地方。5. 部署上线与主题维护中的几个坑5.1 用GitHub Actions自动构建部署配置写好了美化也做完了接下来就是把博客发布到公网。我的选择是GitHub Pages加GitHub Actions在main分支每次推送后自动构建整个过程不需要本地手动执行hugo命令。在项目根目录创建.github/workflows/deploy.ymlname: deploy on: push: branches: [main] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: submodules: true - uses: peaceiris/actions-hugov3 with: hugo-version: 0.123.0 extended: true - run: hugo --minify - uses: peaceiris/actions-gh-pagesv4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./public这个工作流里最容易被忽略的是submodules: true。如果你用submodule方式引入Stack主题但没有这个参数GitHub Actions在拉取代码时不会拉主题构建必挂。如果你倾向用Cloudflare Pages也很简单直接把Git仓库连接到Cloudflare Pages构建命令填hugo --minify环境变量里设置HUGO_VERSION和你本机一致再设置HUGO_EXTENDED1即可。5.2 升级主题与自定义代码的冲突处理Stack主题迭代速度不算慢隔几个月就有小版本更新。升级命令很简单git submodule update --remote themes/hugo-theme-stack但升级后偶尔会遇到两个问题一是新版主题修改了某个模板结构导致你的自定义CSS里对应的选择器失效二是你自己的layouts覆盖文件与新版主题模板字段不匹配。我的经验是定期关注Stack官方仓库的Release说明升级后第一时间跑一遍本地预览重点检查首页列表、文章详情页、代码高亮和分类归档这几个核心页面。由于我们的自定义内容都在主题目录之外升级几乎不会冲突最多需要微调CSS变量名。还有一个常见坑文章图片使用相对路径。如果你图片字段写成image ../img/cover.webp在文章列表页可能正常但进入子目录文章页后浏览器无法正确解析。建议一律使用以/开头的绝对路径目录结构简单清晰部署到任何子路径都不容易出问题。最后再分享一点小经验博客搭好之后最重要的不是继续折腾主题而是开始写。我见过太多人花几周时间调样式、配插件结果一篇文章都没写完。Stack这个主题的好在于它默认状态已经足够耐看你只需要把站点身份信息、内容目录、代码高亮这三处必改配置做完立刻就能投入使用五个美化技巧则完全按需添加不必一次全部做完。我自己的顺序是先解决内容展示和评论再处理CSS变量和封面图规范至于复制按钮这种体验优化是后来某一天觉得“这里不爽”才随手加的。把“打磨”融进日常写作流程而不是在开站前一步到位这大概是让技术博客长期走下去最舒服的节奏。