Hugo + Stack主题：打造极简技术博客的配置与美化指南

我想做极简技术博客的时候第一反应就是 Hugo 配上 Stack 主题。Hugo 是 Go 写的静态站点生成器本地预览、打包都很快Stack 主题则很克制没有花哨的动画也没有硬塞一堆前端框架打开页面就是一屏一屏干净的文字。如果你也想搭一个自己的技术博客或者已经在用 Stack 但觉得默认效果不够有辨识度这篇内容你可以直接照着操作。下面我会把 3 个必改配置和 5 个高级美化技巧拆开讲每一步都带实际文件和代码。另外如果你的 Hugo 项目现在还放在机械硬盘或者移动硬盘上我也会在部署和备份部分专门聊到这个因为硬盘速度对本地预览的影响真比你想象中大。1. 为什么是 Hugo 和 Stack 主题1.1 Stack 主题到底解决了什么问题技术博客的核心需求其实很朴素能写 Markdown、能分类标签、能搜索、能归档、打开速度快。很多博客系统不是做不到而是把简单的事情做复杂了。 WordPress 也能搭技术博客但你可能要先处理插件兼容、缓存插件、安全更新、数据库备份一堆事情。Hexo 和 VuePress 也很火但 Node 生态的构建链路相对重依赖一多升级一次可能就要折腾半天。Hugo 不需要数据库不需要运行时写完 Markdown 后跑一条命令就直接输出整个静态网站。Stack 主题能在国内技术圈流行起来靠的不是功能堆叠反而是“不做多余的事”。它的首页是卡片式文章列表侧边栏放头像、简介、搜索、分类、标签。文章页有目录、阅读时间、上一篇下一篇这些技术博客的刚需功能都有但页面没有多余的弹窗、返利插件、访问计数器之类的东西。对读者来说打开页面就是内容本身对作者来说维护成本低到可以忽略。另外一个容易被忽略的点是移动端体验。Stack 的排版在手机上不需要放大缩小字号和行距都调得比较舒服。这也是我坚持用它做技术博客的原因很多读者第一次访问你的文章可能是在通勤路上如果移动端一塌糊涂内容再硬也留不住人。1.2 动手前的环境准备开始之前你需要先确认电脑上有 Git 和 Hugo。Hugo 建议装 extended 版本因为 Stack 主题的样式用到了 SCSS普通版在构建时会因为缺少相关能力报错。hugo version git --version如果没有安装去 Hugo 官方 GitHub Releases 页面下载对应系统的预编译包即可。安装完以后打开命令行建站hugo new site blog cd blog git init git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/stack这里使用 git submodule 而不是直接下载 zip是方便后续跟进主题更新。如果以后 Stack 主题发布了新版本你只需要在项目目录里执行git submodule update --remote就能更新主题不用手动覆盖文件。拿到主题后先把主题自带的示例站点配置复制到项目根目录cp -r themes/stack/exampleSite/* .这一步很关键。Stack 主题不是只靠一个config.toml就能跑的它把配置拆分到了config/_default/目录下的多个文件里。直接复制 exampleSite能让你少踩很多配置缺失的坑。之后运行hugo server -D浏览器打开http://localhost:1313如果能看到一个带侧边栏的示例博客说明环境已经通了。2. 3个必改配置从默认模板改成自己的博客复制完 exampleSite 之后你看到的仍然是演示内容。接下来要做的 3 个改动是让这个站点真正变成“你的博客”的必经步骤。2.1 必改配置一站点核心参数打开config/_default/config.toml最重要的几个字段如下baseURL https://yourname.example.com languageCode zh-cn title 我的技术博客 theme stack paginate 10 enableEmoji true hasCJKLanguage truebaseURL一定要填你最终部署的完整域名。如果留空或者填成http://localhost:1313/后续生成的 sitemap、canonical、Open Graph 标签都会是错的搜索引擎收录时会出现一堆本地地址。hasCJKLanguage对中文博客非常重要。Hugo 在计算摘要和阅读时间时对中英文的统计方式不同。开了这个参数之后中文文章的自动摘要和阅读时间会更接近真实体验。paginate 10是首页每页显示的文章数量。如果你想走极简风10 篇比较合适如果你的文章普遍很长也可以改成 5 或 6。搜一下某一篇文章标题需要单独设实际上 Hugo 的搜索是 JavaScript 在前端做的。Stack 主题用的是 index.json 索引你只需要在侧边栏配置里加上搜索组件就行。2.2 必改配置二菜单和导航默认的菜单还是示例站点的需要改成你自己的导航。在config/_default/menus.toml里配置大致是这样的[[main]] name 首页 url / weight 1 [[main]] name 归档 url /archives/ weight 2 [[main]] name 标签 url /tags/ weight 3 [[main]] name 关于 url /about/ weight 4这里的weight决定菜单顺序数字越小越靠前。注意 URL 要和你的 content 目录结构对应。比如你想要“关于”页面就得先在 content 下新建hugo new about/index.mdStack 主题的文章和普通页面是分开处理的。普通页面默认不会出现在文章流里而是可以作为独立页面存在。写完/about/的内容后导航里再有对应菜单项页面就能访问到了。我踩过一个坑当时只改了菜单没有新建about页面结果点“关于”直接 404。后来改成先建页面、再改菜单顺序对了就不会有问题。2.3 必改配置三文章模板和摘要策略Hugo 新建每篇文章时会根据archetypes/default.md生成 front matter。你可以把这个模板改成最适合自己习惯的样子--- title: {{ replace .Name - | title }} description: date: {{ .Date }} draft: true tags: [] categories: [] featuredImage: featuredImagePreview: ---featuredImage是文章详情页的封面图featuredImagePreview是列表卡片上用的缩略图。如果只填一个Stack 可能会用同一个图补齐另一个位置。图片路径建议放到static/images/下然后写/images/xxx.jpg。摘要这块新手很容易忽略。Stack 在列表页展示文章摘要时有几种优先级如果在 front matter 里写了description就用它如果没写Hugo 会从正文里自动截取。自动截取的长度由全局配置summaryLength控制默认大概是 70 个词。中文场景下70 个词的自动截断结果常常会切在奇怪的位置。我的建议是每篇文章都手动写description。一来能精确控制列表页的展示效果二来对 SEO 也更友好。如果你有很多旧文章不想回头补直接在config.toml里调大summaryLength也能缓解但不推荐依赖这个方式。3. 5个高级美化技巧把 Stack 调成自己喜欢的样子完成了必改配置之后你的博客已经可以正常用了。但默认的 Stack 主题长什么样你大概也猜得到白色背景、黑色文字、蓝色链接。想让博客有自己的识别度可以从下面 5 个方向入手。3.1 技巧一自定义头像、简介和社交链接Stack 的侧边栏是整站辨识度最高的地方。默认情况下侧边栏会读取主题示例里的人物信息。要改成你自己的信息打开config/_default/params.toml找到 sidebar 相关配置。不同版本的 Stack 主题字段名会有一点点差异但大方向一致。常见的配置内容类似下面这样[sidebar] name 你的名字 bio 写代码也写字 avatar /images/avatar.png如果字段名对不上不要硬记直接打开themes/stack/exampleSite/config/_default/params.toml对照示例。Stack 的文档并不是特别丰富但 exampleSite 本身就是最好的配置说明。头像图建议用 200x200 左右的正方形图片压缩成 WebP 或者压缩过的 PNG。不要直接放一张几 MB 的原图因为侧边栏在每一个页面都会加载图片越小整站越快。社交链接一般放在简介下面比如 GitHub、RSS、Email 这些。RSS 这个一定要留技术博客的老读者很依赖它。3.2 技巧二深色模式和主题色Stack 默认带了深色模式切换按钮不需要你自己写一套 JS。但如果你觉得切换后的默认配色不够有质感可以通过自定义 CSS 覆盖。Stack 支持在项目根目录创建assets/css/custom.css这个文件会被主题自动合并。你不需要修改主题源码就能覆盖大部分样式。举个例子我想让链接色从默认的蓝改成更沉稳的靛蓝色:root { --stack-color-link: #2563eb; } [data-themedark] { --stack-color-link: #60a5fa; }这里用到了 CSS 变量。Stack 主题的很多颜色都是变量控制的你只要在浏览器的开发者工具里选中正文区域就能看到当前生效的颜色变量名。改的时候注意不要一上来就加!important优先修改变量这样主题升级时不容易冲突。如果你只是想给卡片加点圆角和阴影也可以直接在 custom.css 里写.article-card { border-radius: 12px; box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06); }极简不等于没有质感适当的圆角和阴影能让页面显得更精致。但别陷入过度设计。我见过不少博客最后视觉上很花哨字体一大堆颜色也五花八门反而不如默认清爽。3.3 技巧三用 Shortcode 自制提示框写技术文章经常要表达“注意”“警告”“推荐”这类信息。如果每次都用引用块时间久了视觉上会很单调。Hugo 的 Shortcode 机制允许你自定义内容组件Stack 本身已经支持了一些但你也可以自己加。在layouts/shortcodes/notice.html里创建一个提示框模板div classnotice {{ .Get type }} div classnotice-title{{ .Get title }}/div div classnotice-body{{ .Inner | markdownify }}/div /div然后在assets/css/custom.css里加一点样式.notice { border-left: 4px solid var(--stack-color-link); background: rgba(0, 0, 0, 0.03); padding: 12px 16px; margin: 20px 0; border-radius: 4px; } .notice-title { font-weight: 700; margin-bottom: 6px; }写文章的时候这样用{{ notice typewarning title注意 }} 这里的内容会显示在提示框里。 {{ /notice }}这种方法的好处是提示框的样式和内容分离。如果你以后想换风格只改一处 CSS 就能全局生效。3.4 技巧四定制文章元信息、标签样式和阅读进度条Stack 默认会在文章头部显示日期、阅读时间、作者这些信息。这些东西本身够用但如果你希望它更符合个人习惯可以修改文章卡片对应的 partial 文件。Stack 的文章 header 相关模板在themes/stack/layouts/partials/article/components/下你可以把想改的文件复制到项目的layouts/对应目录里覆盖而不是直接改主题目录。标签样式也是很容易出效果的地方。默认标签就是一个普通链接你可以把它改成胶囊样式.tags a { border: 1px solid var(--stack-color-link); border-radius: 999px; padding: 2px 10px; margin-right: 6px; font-size: 0.85rem; }这会让文章底部的标签区域看起来更整洁也不会显得花哨。阅读进度条是 Stack 默认没有的东西。如果你实在想要可以在layouts/partials/reading-progress.html里写一小段脚本然后在baseof.html的底部引入。但我要提醒一句改baseof.html意味着主题升级时需要手动合并。我的做法是只在 baseof 里保留一行 include其他代码全部抽到独立 partial 文件里这样升级冲突的概率会低很多。实际上Stack 默认已经在文章页显示了阅读时间。我用了阅读进度条一段时间后还是觉得默认的“预计阅读 X 分钟”更省心。博客到底要不要加这个取决于你自己。3.5 技巧五SEO、Open Graph 和分享图美化不只停留在页面视觉搜索引擎和社交平台上的展示效果也属于博客形象的一部分。Hugo 自带 Open Graph 模板但你需要把baseURL配好。否则对方在微信、Twitter 里分享你的链接时抓取到的地址都是错的。如果想给整站设定一个默认分享图把一张 1200x630 左右的图片放到static/images/og-default.png然后在config/_default/params.toml里指定images [/images/og-default.png]单篇文章可以用 front matter 里的featuredImage或images来覆盖默认分享图。分享图不要用太小的图社交平台会对小图进行模糊放大效果很差。建议用文字加上简单底色的风格这样在聊天窗口里一眼就能看出是哪篇文章。另外建议在每篇文章的 front matter 里写description。这个描述不仅会在列表页显示也会被搜索引擎用来做搜索摘要。没有摘要的文章在搜索结果里可能就是一段断句混乱的正文截取点击率会明显受影响。4. 从硬盘到线上构建、部署与备份配置和美化都做完之后接下来就是把博客真正发布到线上。这个环节看着简单但如果你没有处理好本地目录和部署流程后面维护会很难受。4.1 本地预览和构建日常写作时我会用hugo server -D-D是让草稿文章也出现在本地预览里。写完后正式构建时建议加--gc和--minifyhugo --gc --minify--gc会清理构建缓存里的无用文件--minify会把 HTML、CSS、JS 压缩。构建完成后public/目录就是整站静态文件。你可以扔给任何静态托管服务不需要服务器执行代码。如果你在本地想验证生产环境效果不要直接双击public/index.html。正确做法是起一个静态服务器python3 -m http.server 8080 -d public然后访问http://localhost:8080。直接用file://协议打开时很多静态站点的路径和资源加载会出问题但那不是你的博客有问题而是本地协议限制。关于硬盘这块我想多说一句。Hugo 的构建速度虽然快但在机械硬盘或者移动硬盘上跑文件监听和资源写入都会明显变慢。我第一次把项目放在移动硬盘上写博客时hugo server每次保存文件后的热更新都要好几秒后来把项目移到 SSD 上基本是保存完立即刷新。所以建议项目源码放在 SSD 上开发移动硬盘用来做冷备而不是直接当开发目录。4.2 部署到托管平台Hugo 的部署方式非常多。最简单省心的是用 Git 托管平台自带的静态站点能力或者用支持 Hugo 构建的 Pages 服务。我用下来最舒服的方式是 GitHub Actions 自动构建。只要往主分支 push就会自动构建并发布。一个能用的 GitHub Actions 配置大概是这样的name: deploy on: push: branches: [main] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: submodules: recursive - uses: peaceiris/actions-hugov3 with: hugo-version: 0.138.0 extended: true - run: hugo --minify - uses: peaceiris/actions-gh-pagesv4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./public这里最容易漏掉的是with: submodules: recursive。如果你用 git submodule 添加主题没有这一项GitHub Actions 拉代码时不会拉主题构建必然失败。部署完之后一定要去检查https://你的域名/sitemap.xml是否正常然后去 Google Search Console 或 Bing Webmaster 提交站点。Hugo 会自动生成 sitemap但搜索引擎不会主动知道你建了博客需要你手动提交。4.3 硬盘上的 Hugo 站点备份很多技术博主只备份public目录这是错误的。public是从源码生成的产物丢了可以从源码重新构建。真正不能丢的是你的源码源文件、图片资源、config/_default/配置文件、主题版本信息。我的备份习惯是整个项目目录同步到移动硬盘同时推送到私有 Git 仓库。Git 仓库只需要包含以下内容content/文章源代码assets/自定义样式和布局static/图片和其他静态资源config/配置目录.gitmodules主题子模块信息go.mod或go.sum如果有模块依赖themes/stack因为是 git submodule不需要单独备份但.gitmodules文件必须保留。没有这个文件换一台电脑后你很难知道自己用的是哪个版本的主题。如果你把整个项目放在机械硬盘上做备份建议压缩成 tar 或 zip不要只靠散文件。因为机械硬盘长期通电后坏道风险会增加压缩成一个归档文件至少能减少碎片化存储带来的问题。5. 常见问题与排查技巧实录这个部分是我实际使用 Hugo Stack 过程中踩过的坑整理成速查表方便你遇到问题时直接对照。现象常见原因解决办法页面样式全部丢失baseURL配错或者没有拷贝 exampleSite 的配置目录检查config/_default是否存在确认baseURL是完整域名首页文章列表不显示params.toml里的mainSections和你的 content 目录不一致把mainSections改成实际存放文章的 section比如[posts]或[blog]搜索功能没结果本地预览时页面协议限制或者没有生成 index.json部署线上再测本地可以用静态服务器访问而不是file://本地刷新很慢项目在机械硬盘或者移动硬盘上文件监听跟不上把项目移到 SSD或使用hugo server --renderToMemory5.1 页面样式全丢如果你本地打开页面发现完全没样式第一步检查浏览器开发者工具里的网络请求看看 CSS 文件返回的是 404 还是正常。如果是 404多半是配置目录不完整。Stack 主题的主题样式位于themes/stack/assets/css/但真正启用它需要 config 里正确指定theme stack并且确保assets目录下的自定义文件没有语法错误。5.2 文章列表不显示Stack 默认的mainSections是[posts]。也就是说它只会在content/posts/目录下找文章。如果你习惯把内容放在content/blog/但mainSections没改首页就会是空的。修改方式是在params.toml里加上mainSections [blog]注意这个字段是数组结构不要写成mainSections blog。多个目录也可以比如[posts, notes]。5.3 标签和分类页打不开Stack 的分类、标签页依赖 taxonomy 特性。如果你的 config 里没有正确配置相关内容标签页会 404。检查config.toml里有没有[taxonomies] tag tags category categories如果没有Hugo 就不知道tags和categories是什么自然无法生成对应页面。这个字段一般 exampleSite 里已经带上了如果你是自己从空项目开始搭的很容易漏。5.4 主题升级后自定义样式丢失很多人喜欢直接改themes/stack底下的文件。这样做不是不行但每次git submodule update --remote更新主题时你的修改会被覆盖。正确做法是把要覆盖的模板复制到项目根目录的layouts/下让项目的layouts优先级高于主题的layouts。这样升级主题时项目级文件不会被覆盖。我在升级 Stack 主题时遇到过一个问题主题改了某个 CSS 类名我之前写在 custom.css 里的选择器失效了。排查方式很简单打开线上页面查看具体元素的 class再和 custom.css 里的选择器对比。如果发现失效更新选择器就好。最后再说一个我自己的习惯。每次写完文章我不会直接 push而是先跑一遍hugo --gc --minify再本地起一个静态服务器把新文章点开看一眼封面图有没有显示、代码高亮是否正常、标签链接能不能点、分享出去之后标题和摘要对不对。确认没问题再推远端。这个顺序帮我省掉了非常多线上问题。博客不是越复杂越好。Hugo 加 Stack 这套组合最核心的价值就是把维护成本压到最低让你把时间留给写作本身。至于那些美化技巧选你自己真正喜欢的够用就好。如果你按照上面这些步骤走完接下来要做的就是安安心心写第一篇正式文章了。