Hugo 搭建 Solitude 博客：小白零基础安装配置与宝塔部署

想要一个不用数据库、打开飞快、还自带高颜值主题的个人博客?试试用 Hugo 搭建 Solitude 主题博客:本文从安装 Hugo、创建站点、逐项配置主题功能讲起,再到打包静态文件、部署到宝塔面板上线,全程零基础可复现。每一条命令我都标注了「完成标志」——看到什么输出才算成功、才能进行下一步,我实操时踩过的坑和真实报错也一并整理给你。

说明:本文由 宝藏秀 整理,在个人虚拟机里全程实操写成,演示截图均为真实操作,供建站前参考。

Hugo 和 Solitude 主题是什么

静态博客生成器的工作思路很简单:你在本地用 Markdown 写文章,它在发布前把所有页面一次性生成纯 HTML,访客打开的就是现成的文件。Hugo 是这类工具里知名度最高的一个,使用 Go 语言编写,单文件运行、不需要安装数据库,官方宣传语就是「世界上最快的网站构建工具」,几千篇文章的站点通常一秒内就能构建完成。

Solitude 原本是 Hexo 平台上颇受欢迎的高颜值主题,后来作者发布了原生 Hugo 版(仓库 everfu/hugo-solitude),保留了熟悉的视觉与交互:首页轮播横幅、可组合的侧栏组件、即刻短文、留言信封、音乐馆、本地搜索、键盘快捷键等,功能相当齐全,而且构建过程不依赖 Node.js。

和传统的动态博客(比如 WordPress)相比,静态博客的特点可以看这张表:

准备工作

整个过程只需要三样东西,列成清单方便对照:

1. 一台 Windows 电脑:用于安装 Hugo、写作和生成站点文件(Windows 10 及以上均可);
2. Git for Windows:用来克隆主题仓库,安装时全部选默认选项、一路下一步即可;
3. 装好宝塔面板的服务器:用来部署上线,推荐 Ubuntu 22.04 或 Debian 12。

服务器如果还没有着落,可以看看雨云服务器,注册时填写优惠码 quzai 能领一张五折优惠券,拿一台最低配跑静态站绰绰有余。

关于演示环境,先说清楚:本文的宝塔面板安装在我个人的本地虚拟机里,面板地址、服务器 IP(192.168.200.100)都是内网演示用途;你操作时,面板地址用你自己服务器的,站点域名填你自己的域名。文中不会出现任何真实密码,遇到需要输入账号密码的地方都以占位符代替。

第一步:安装 Hugo

下载安装包,注意别下错文件名

打开 GitHub 的 Hugo 发布页(github.com/gohugoio/hugo/releases),找到最新版本,展开页面下方的 Assets 列表,下载 Windows 平台的压缩包。这里有个我当时就踩到的坑:列表里有好几个长得像的文件,一定要认准同时带 extended 和 windows-amd64 字样的那一个:

• 正确:hugo_extended_0.166.0_windows-amd64.zip
• 不要下:hugo_0.166.0_windows-amd64.zip(标准版,缺少扩展特性)、hugo_extended_withdeploy_…(附带部署功能,用不上)

我第一次就按印象拼了个文件名,结果下载回来的「压缩包」只有 9 字节——其实是 404 页面,解压直接报错。文件名拼错时 GitHub 不会提示 404,而是把错误页面存成了文件,这点要留意。Solitude 主题要求 Hugo 不低于 0.164 版本,直接下最新版即可。

解压并配置环境变量

在 C 盘根目录新建一个 Hugo\bin 文件夹(资源管理器地址栏输入 C:\Hugo\bin 回车,系统会提示新建,确认即可),把压缩包里的 hugo.exe 解压进去。接着右键「此电脑 → 属性 → 高级系统设置 → 环境变量」,在上半部分的「用户变量」里选中 Path,点「编辑 → 新建」,填入 C:\Hugo\bin,然后一路点「确定」保存。

技巧:环境变量只对新开的窗口生效,已经打开的终端不会认。关掉旧窗口,从开始菜单重新打开一个 PowerShell,输入下面这条命令验证(这条可以直接复制):

hugo version

完成标志:终端回显一行版本号,并且里面带有 extended 字样,例如下面这样(这是我虚拟机里的真实输出):

PS C:\Users\demo> hugo version
hugo v0.166.0-78400b4de8adc99273d3e674ed6c4d14c3bdf669+extended windows/amd64 BuildDate=2026-09-09T14:45:02Z VendorInfo=gohugoio

PS C:\Users\demo>

如果提示 hugo 不是内部或外部命令,说明环境变量没配对或者窗口没重开:检查 Path 里是不是 C:\Hugo\bin(指向文件夹,不是指向 hugo.exe),确认后重开窗口再试。

第二步:创建站点并安装 Solitude 主题

在项目文件夹里打开 PowerShell

先在磁盘上建一个放博客的文件夹,比如 H:\项目\网站搭建教程(路径别带特殊符号)。进入这个文件夹后,在资源管理器的地址栏里直接输入 powershell 回车,就会在当前路径打开一个 PowerShell 窗口,省去敲 cd 的麻烦。

生成站点骨架

执行下面的命令,myblog 是站点文件夹的名字,可以换成自己喜欢的:

hugo new site myblog
cd myblog

完成标志:输出 Congratulations! Your new Hugo site was created in …,并且当前目录下多出一个 myblog 文件夹。这条命令做的事:生成一套标准站点骨架——content 放文章、themes 放主题、static 放静态资源。

克隆 Solitude 主题

继续执行:

git clone --depth 1 -b hugo https://github.com/everfu/hugo-solitude.git themes/solitude

完成标志:出现 Cloning into 'themes/solitude'...,随后命令安静地返回提示符、没有报错,并且 themes\solitude 文件夹里能看到 layouts、exampleSite 等目录。这条命令把主题源码下载到 themes/solitude;-b hugo 表示拉取主题的 Hugo 分支,别漏掉;--depth 1 只拉最新一个版本,下载更快。如果进度条长时间卡住或提示连接超时,是访问 GitHub 不稳定,重试一两次或换个网络。

复制示例内容,少走弯路

主题自带一套可以运行的示例站,直接把它的内容搬过来当起点:打开 myblog\themes\solitude\exampleSite 文件夹,把里面 content、data、static、archetypes 四个文件夹复制到 myblog 根目录下(和 themes 同级)。它们分别是:文章与页面、功能页数据文件、媒体资源、文章模板。

建立配置文件

在 myblog 根目录新建一个文本文件,命名为 hugo.yaml(注意后缀是 yaml 不是 txt,资源管理器需开启「显示文件扩展名」),先把下面这段最小配置贴进去,完整的功能配置下一步再逐块加:

theme: solitude            # 指定 themes/ 下的 solitude 主题,必填!
baseURL: http://127.0.0.1:1313/    # 本地预览先这样填,部署前改成你的域名
title: 宝藏秀
locale: zh-CN
defaultContentLanguage: zh-cn
timeZone: Asia/Shanghai
enableRobotsTXT: true

uglyURLs:
  posts: true

permalinks:
  posts: /p/:slug          # 文章链接固定为 /p/文章slug.html

outputs:
  home: [HTML, RSS, Search, Links]   # 首页额外输出搜索索引与友链数据

两个必踩的坑提前说:其一,hugo new site 会在根目录生成一个 hugo.toml,要把它删掉——两个配置文件并存时 hugo.toml 优先,你写的 hugo.yaml 会整体失效(报错样子见踩坑专区);其二,theme: solitude 一行绝对不能漏,漏了就等于在没有主题的状态下构建。删文件用这条命令:

Remove-Item hugo.toml

完成标志:PowerShell 删除类命令没有任何输出、直接回到提示符就是成功(Windows 命令的惯例:没消息就是好消息),用资源管理器确认根目录里已经没有 hugo.toml。

第三步:完成主题全量配置

Solitude 的所有功能都集中在 hugo.yaml 一个文件里管理,把下面几块依次追加到配置文件里(YAML 对缩进敏感,注意保持和示例一致的缩进),保存即生效。官方完整示例在 themes/solitude/exampleSite/hugo.yaml,拿不准某项含义时可以对照。

站长信息与首页推荐位

params:
  author:
    name: 野趣
  description: 宝藏秀(haomc.com)官方演示博客,专注技术教程与资源分享
  solitude:
    hometop:
      recommendList:        # 首页右侧推荐卡片,最多 5 条,不足自动补最新文章
        - title: 开始使用 Solitude Hugo
          url: /p/getting-started.html
          cover: /img/demo/cover-getting-started-v2.webp
          label: 快速开始
          color: "#3b82f6"

提醒一点:配置里的 hometop.banner(横幅文字)在 Hugo 版里并不生效,首页横幅实际由 recommendList 加最新文章自动轮播组成,不用浪费时间找开关。

侧栏组件与建站时间

    aside:
      home:
        noSticky: about
        Sticky: newestPost,allInfo      # 侧栏吸底组件组合,可自由增删
      my_card:              # 侧栏作者卡片
        author:
          img: /img/default_avatar.avif
          emoji: "📝"
        description: 宝藏秀演示站,站长 @野趣。
        content: 更多教程与资源,欢迎访问 haomc.com 宝藏秀。
        witty_words: [保持好奇, 慢慢积累, 记录即成长]
      siteinfo:
        runtime: 2025-06-01 00:00:00   # 建站时间,运行天数从这里起算

文章页功能与版权

    post:
      meta:
        date: true
        updated: true
        wordcount: true
        readtime: true      # 字数、阅读时长等元信息
      covercolor:
        enable: true        # 封面主色自动晕染到页面
        mode: local
      share:
        enable: true
        list: [link, weibo, facebook]
    expire:                 # 文章过期提醒
      enable: true
      time: 30
      position: top
    copy:                   # 复制超 50 字自动追加版权
      enable: true
      copyright:
        enable: true
        limit: 50

特色功能页:一键全部开启

主题最出彩的几个「特色页」都在 params.solitude 下用 enable: true 打开,页面内容文件放在 data/ 目录:

    brevity:                # 即刻短文(说说)
      enable: true
      page: /brevity/
      home_mini: true       # 首页底部同步展示最新短文
    envelope:               # 留言板信封动画
      enable: true
      page: /message/
    music:                  # 音乐馆(网易云歌单)
      enable: true
      id: "8407304077"      # 换成你自己的歌单 ID
      server: netease
      type: playlist
    capsule:                # 悬浮音乐胶囊
      enable: true
      id: "8407304077"
    keyboard:               # 键盘快捷键(Shift+D 切深色等)
      enable: true
    search:                 # 本地搜索,无需外部服务
      enable: true
      type: local
      local:
        preload: true

改完配置后站点文件夹结构应该长这样,对照检查一遍:

myblog
├─ archetypes/   文章模板(来自 exampleSite)
├─ content/      文章与页面(来自 exampleSite)
├─ data/         功能页数据:about、links、brevity、kit
├─ static/       媒体资源(来自 exampleSite)
├─ themes/
│  └─ solitude/  主题本体
└─ hugo.yaml     全站配置

说明:评论系统(Twikoo/Waline 等)和 PWA 两项这次刻意没开:前者需要额外部署评论后端,后者要求 HTTPS 环境才生效,都适合等站点上线后再加,配置写法在「可选优化」里留了位置。

第四步:写文章与本地预览

新建文章

执行下面的命令,文件名建议用英文短横线命名:

hugo new posts/my-first-post.md

完成标志:输出 Content "…\content\posts\my-first-post.md" created,并且在 content\posts 目录里能看到这个文件。

用 VS Code、记事本等任意编辑器打开它,头部 front matter 决定这篇文章的各项属性,其中 slug 一行务必自己写上,否则链接会变成一长串中文(原因见踩坑专区第三条):

---
title: 我的第一篇博客文章
slug: my-first-post
date: 2026-09-10T07:08:42+08:00
description: 文章摘要,会出现在列表卡片与搜索结果里
cover: /img/demo/cover-pagination-v2.webp
categories: [随笔]
tags: [Hugo, Solitude, 起步]
comment: true
toc: true
draft: false
---

正文用 Markdown 书写,写完保存即可。

启动本地实时预览

hugo server

完成标志:看到这两行就说明服务已经跑起来了,可以进入下一步:

PS H:\项目\网站搭建教程\myblog> hugo server
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://127.0.0.1:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

PS H:\项目\网站搭建教程\myblog>

浏览器打开 http://127.0.0.1:1313,就能看到站点真容。这个窗口不要关,它负责实时预览:改动配置或文章保存后页面会自动刷新;想停止服务时在窗口里按 Ctrl+C。如果提示端口被占用,改用 hugo server --port 1314 换个端口。这个阶段可以反复调整到满意为止:

首页顶部是轮播横幅加推荐列表,右侧作者卡片、最新文章等组件都来自 aside 配置;左下角的悬浮音乐胶囊说明音乐功能已生效。

文章页自带目录侧栏、字数与阅读时长统计,页底有版权卡片和分享按钮。

即刻短文页面,适合发一句话动态,数据维护在 data/brevity.yaml 里,写起来像发朋友圈一样轻量。

第五步:生成静态文件并打包

本地满意后,正式生成生产文件。注意先检查 baseURL:它必须与你最终的访问地址一致(本文演示是服务器 IP,正式使用请换成你的域名,并带上 http 前缀),否则页面里部分资源链接会指向错误地址,表现为样式错乱、图片裂开。改好后执行两条命令:

hugo --gc --minify
Compress-Archive -Path .\public\* -DestinationPath $HOME\Desktop\blog.zip -Force

第一条是生产构建,--gc 清理构建缓存、--minify 压缩输出,结果生成到 public 文件夹。完成标志:输出统计表格(显示 Pages 数量)和 Total in … ms,并且没有 ERROR 开头的行;出现 ERROR 时,把报错文字拉到踩坑专区对照处理。第二条调用 PowerShell 自带的压缩功能,把 public 里的全部内容打包到桌面 blog.zip,完成标志:命令无输出直接返回,桌面出现 blog.zip(约 8~9 MB),这就是要上传到服务器的完整站点。

第六步:部署到宝塔面板

登录你的宝塔面板(地址、账号密码在面板安装完成时会显示,注意保管,别泄露给任何人)。进入左侧「网站」页:

添加一个纯静态站点

点击「添加站点」,按下表填写。域名一栏填你自己的域名;本文在虚拟机里演示,没有解析域名,就临时填了服务器内网 IP:

完成标志:提交后弹出建站成功提示,站点列表里出现你的站点、状态为「运行中」。PHP 版本务必选「纯静态」。

上传压缩包并解压

点站点记录里的根目录路径,进入文件管理器。先删掉宝塔默认生成的 index.html 和 404.html(留着旧的 index.html 会导致访问的还是默认页),再点左上角「上传 → 上传文件」,选择桌面的 blog.zip,点「开始上传」。完成标志:上传窗口显示绿色「上传成功: 1个」。

在文件列表里找到 blog.zip,点右侧「解压」,解压路径保持当前目录不动,确认后几秒内完成。最后把 blog.zip 本体删掉,保持根目录干净:

完成标志:刷新文件列表,根目录里出现 index.html、404.html 以及 about、posts、p、tags 等一批目录,这就是 Hugo 生成的完整站点。

访问验证

浏览器直接输入服务器地址(本文演示是 http://192.168.200.100,你则是你的域名),博客首页正常打开,部署完成:

完成标志:页面标题是你的站名、样式正常、文章能点开。如果显示的还是宝塔默认页,回上一步检查 index.html 是否被覆盖,浏览器按 Ctrl+F5 强刷缓存。以后更新文章,重复「第五步生成打包 → 第六步上传解压覆盖」即可,全程两三分钟。

踩坑专区:三个真实报错与解法

坑一:安装包下载成 404 页面,解压失败

手拼下载链接或者看花眼时,下载回来的 hugo.zip 只有 9 字节,解压报「找不到中央目录」。这不是下载工具坏了,是文件名不对,GitHub 把 404 页面存成了文件。

解决办法:回到 Releases 页面点开 Assets 列表,完整复制 hugo_extended_版本号_windows-amd64.zip 这个文件名下载;下载完先看体积,正常应有 20 MB 以上。

坑二:构建报 shortcode not found

装好主题、写好配置,一构建却满屏报错:

PS H:\项目\网站搭建教程\myblog> hugo
Start building sites …
Total in 15 ms
ERROR error building site: assemble: failed to create page from pageMetaSource /posts/shortcodes: "H:\项目\网站搭建教程\myblog\content\posts\shortcodes.md:19:1": failed to extract shortcode: template for shortcode "note" not found

PS H:\项目\网站搭建教程\myblog>

这个报错极具迷惑性——主题里明明有 note 这个 shortcode,报错却说找不到。实际原因有两个,我全踩中了:一是 hugo new site 默认生成的 hugo.toml 没删,我又自作主张建了 hugo.yaml,两个配置并存时前者优先生效,我写的 theme: solitude 根本没被读到,等于在没有主题的状态下构建。

解决办法:删掉 hugo.toml,确保配置文件里写有 theme: solitude,再构建即可通过。修复后重新构建,看到统计表格和 Total in … ms、没有任何 ERROR,就说明站点骨架全部生成成功:

PS H:\项目\网站搭建教程\myblog> hugo
Start building sites …

                  │ ZH-CN
──────────────────┼─────────
 Pages            │      61
Total in 486 ms

PS H:\项目\网站搭建教程\myblog>

坑三:文章 URL 变成一长串中文

用 hugo new 建的新文章,如果 front matter 里没写 slug,生成的链接会变成 /p/我的第一篇博客文章.html 这种中文长链接,访问时是一串百分号编码,难看又不利于分享。

解决办法:每篇文章的 front matter 都手动加一行 slug: 英文短横线命名,链接就会固定为 /p/slug.html。permalink 里用了 :slug 变量,slug 就要自己给,这一条是全文最值得记住的细节之一。

部署后的可选优化

绑定域名与 HTTPS

域名解析到服务器 IP 后,在宝塔「网站 → 设置 → 域名」里把域名加进站点,然后改 Hugo 配置里的 baseURL 为 https://你的域名/,重新生成上传一遍。接着在「SSL」页签用 Let’s Encrypt 一键签发免费证书,开启强制 HTTPS。PWA 功能也只有在 HTTPS 生效后才能开启,届时把配置里 pwa.enable 改为 true 即可。

开启评论系统

Solitude 的评论区通过 comment.use 指定后端,支持 Twikoo、Waline、Artalk、Valine 等。以轻量的 Twikoo 为例,在宝塔用 Docker 部署服务端后,填入配置即可:

    comment:
      use: twikoo
    twikoo:
      envId: https://你的评论服务地址
      style: true

开启后,文章元信息里的评论数、侧栏最新评论、留言板评论列表都会自动联动,这些正是本文暂未开启的部分。

常见问题

• 提示 hugo 不是内部或外部命令?环境变量没生效:确认 C:\Hugo\bin 已加入用户 Path,然后关闭窗口重新打开一个再试。
• 部署后样式错乱、图片不显示?九成是 baseURL 与实际访问地址不一致,改配置后重新构建上传。
• 访问还是宝塔默认欢迎页?旧的 index.html 没有被覆盖,先删默认文件再解压;浏览器也顺手强刷(Ctrl+F5)清缓存。
• 新写的文章构建后看不到?检查 front matter 里是否还是 draft: true,草稿状态默认不渲染,改成 false 或删掉这一行。
• 主题怎么更新?进入 themes/solitude 执行 git pull,本地重新构建上传;更新前先备份自己改过的文件。

安全提醒

本文演示里的面板地址、账号、密码均为占位或内网虚拟机环境,请勿把任何一篇教程里的凭据当真使用。你自己的宝塔面板安全入口、账号密码、SSH 端口属于敏感信息,不要截图发到网上;服务器建议改掉默认 SSH 端口、使用密钥登录,并在宝塔「安全」页限制面板的访问来源。文章里的歌曲 ID、示例邮箱等也请替换为自己的。

整个流程走下来,核心其实只有一句话:静态博客把复杂度留在了「生成」这一步,部署只是复制文件。先让站点跑起来,再逐项打磨配置,写作的惯性比任何完美设置都重要。

本文由 宝藏秀 整理发布,更多建站与折腾记录,欢迎常来。