建站记录

Hugo搭建记录

HUGO搭建 UBUNTU

安装

下载最新的 Hugo 扩展版 .deb 文件

Hugo 的扩展版支持 Sass 处理和 WebP 图片编码等功能，并且博主使用的stack主题需要扩展版支持，所以没用apt安装标准版hugo，从 Hugo 的官方 GitHub页面下载最新的 .deb 文件:

  • 使用 wget 下载最新的 Hugo 扩展版 .deb 文件：

    1wget https://github.com/gohugoio/hugo/releases/download/v0.145.0/hugo_extended_0.145.0_linux-amd64.deb
    • 你可以访问 Hugo GitHub Releases 确认最新版本，并确保下载文件名包含 extended 和 linux-amd64（适用于 64 位 Ubuntu 系统）。

安装 Hugo 扩展版

下载完成后，使用 dpkg 安装 .deb 文件：

1sudo dpkg -i hugo_extended_0.145.0_linux-amd64.deb

  • 如果出现依赖问题，可以运行以下命令修复：

    1sudo apt-get install -f

  • 验证安装是否成功：

    1hugo version

    输出类似 hugo v0.145.0-xxx+extended linux/amd64 表示扩展版安装成功。

注意事项

  • 版本更新：每次 Hugo 发布新版本时，重复步骤 1.1 和 1.2 下载并安装最新的 .deb 文件。
  • 权限问题：如果解压 Go 时遇到权限问题，使用 sudo 运行命令。
  • 系统架构：确保下载的 .deb 文件和 Go 文件匹配你的系统架构。

安装并配置 Go

Hugo 是用 Go 语言编写的，虽然普通使用不需要 Go，但如果你需要使用 Hugo Modules 或编译自定义版本，Go 是必需的。以下是安装和配置步骤：

  • 下载最新 Go 二进制文件：

    访问 Go 官网下载页面，找到最新版本，下载适用于 Linux 的 tarball：

    1cd /tmp
2wget https://go.dev/dl/go1.22.1.linux-amd64.tar.gz

  • 解压并安装 Go：

    将文件解压到 /usr/local：

    1sudo tar -C /usr/local -xzf go1.22.1.linux-amd64.tar.gz

  • 配置 Go 环境变量：

    编辑 ~/.profile 文件，添加以下内容：

    1echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.profile
2echo 'export GOPATH=$HOME/go' >> ~/.profile
3应用更改：
4
5```bash
6source ~/.profile

    验证 Go 安装：

    1go version

    输出类似 go version go1.22.1 linux/amd64 表示 Go 配置成功。

    Hugo 根目录文件夹说明

文件夹/文件说明注意事项
archetypes/内容模板目录，用于定义新文件（如hugo new）的默认 front matter默认包含default.md，可自定义其他模板
assets/资源文件目录，存放 SCSS、图片等，通过 Hugo Pipes 处理（如编译 SCSS 为 CSS）需在hugo.yaml 中配置支持（如 assets.dir）
content/内容文件目录，存放 Markdown 文件，按类型组织（如content/post/ 表示文章）文件名决定 URL（如my-post.md -> /post/my-post/）
data/数据文件目录，存放 YAML、JSON 或 TOML 文件，用于动态数据（如导航菜单数据）在模板中通过.Site.Data 访问
layouts/自定义模板目录，覆盖主题的默认模板优先级高于themes/ 中的同名模板
public/生成的静态站点输出目录，构建后内容在此每次运行hugo 会清空并重新生成
static/静态文件目录，存放图片、CSS、JS 等，直接复制到站点根目录不经 Hugo 处理，直接输出到public/
themes/主题目录，存放下载或自定义的主题（如hugo-theme-stack）通过theme 配置启用
hugo.yaml主配置文件，定义站点设置（如语言、主题、URL 等）支持 YAML、TOML、JSON 格式

创建 Hugo 站点并测试

安装好 Hugo 和 Go 后，可以创建一个简单的博客站点测试环境：

创建新站点：

1hugo new site myblog
2cd myblog

编辑配置文件

  1#在站点的根目录下编辑配置文件,配置文件有toml和yaml格式，
  2#博主使用的yaml格式;下面是hugo.yaml文件的内容，根据需要修改：
  3
  4#博主测试baseURL和baseurl设置不生效，
  5#启动hugo 服务时hugo server --baseURL="https://www.test.com/" 测试可以
  6baseurl: https://www.test.com/ # 网站的根 URL，用于生成绝对链接 实际测试不生效
  7
  8languageCode: en-us # 默认语言代码，设置为英语（美国）
  9theme: hugo-theme-stack # 使用的主题名称，这里是 Stack 主题
 10title: 网站标题  # 网站标题，显示在浏览器标签和页面上
 11copyright: 版权声明 # 版权声明，显示在页面底部
 12
 13pagination:  # 分页设置
 14  pagerSize: 10  # 每页显示的文章数量
 15
 16# languages:  # 多语言支持配置（已注释）
 17#     en:  # 英语配置
 18#         languageName: English  # 语言名称
 19#         title: 网站标题  # 英语版网站标题
 20#         description: Blog  # 英语版网站描述
 21#         weight: 1  # 语言权重，决定显示顺序
 22#     zh-cn:  # 中文配置
 23#         languageName: 中文  # 语言名称
 24#         title: 网站标题  # 中文版网站标题
 25#         description: 博客  # 中文版网站描述
 26#         weight: 2  # 语言权重，决定显示顺序
 27
 28# Change it to your Disqus shortname before using
 29# disqusShortname: stack  # Disqus 评论系统的短名称，需替换为你的 Disqus ID
 30
 31# GA Tracking ID
 32#googleAnalytics:  # Google Analytics 跟踪 ID（已注释，未启用）
 33
 34# Theme i18n support
 35DefaultContentLanguage: zh-cn  # 默认内容语言，设置为中文（简体）
 36
 37# Set hasCJKLanguage to true if DefaultContentLanguage is in [zh-cn ja ko]
 38hasCJKLanguage: true  # 启用 CJK（中文、日文、韩文）语言支持，用于正确分词
 39
 40relativeurls: true          # 启用相对 URL，所有链接将基于当前页面路径生成，而不是绝对路径
 41canonifyurls: false         # 禁用 URL 规范化，保持原始 URL 不被转换为绝对路径
 42uglyurls: false             # 禁用“丑陋 URL”，生成的链接将使用更友好的格式（无 .html 后缀等）
 43
 44permalinks:                 # 定义永久链接（URL）的结构
 45  page:                     # 针对单个页面的 URL 配置
 46    home: /posts/:year/:month/:slug/        # 主页文章的链接格式，例如 /posts/2025/03/my-post/
 47    post: /posts/:year/:month/:slug/        # 博客文章的链接格式，例如 /posts/2025/03/my-post/
 48    about: /about/:slug/                    # 关于页面的链接格式，例如 /about/introduction/
 49    article: /articles/:year/:month/:slug/  # 文章页面的链接格式，例如 /articles/2025/03/my-article/
 50    categories: /categories/:year/:month/:slug/  # 分类页面的链接格式，例如 /categories/2025/03/tech/
 51    doc: /docs/:year/:month/:slug/          # 文档页面的链接格式，例如 /docs/2025/03/guide/
 52    search: /search                         # 搜索页面的固定链接，例如 /search
 53  section:                  # 针对页面类型的整体部分的 URL 配置
 54    home: /posts/           # 主页部分的链接，例如 /posts/
 55    posts: /posts/          # 博客部分的链接，例如 /posts/
 56    about: /about/          # 关于部分的链接，例如 /about/
 57    article: /articles/     # 文章部分的链接，例如 /articles/
 58    categories: /categories/ # 分类部分的链接，例如 /categories/
 59    about: /docs/           # 注意：这里与上面的 about 重复，可能应改为 docs，文档部分的链接，例如 /docs/
 60    search: /search/        # 搜索部分的链接，例如 /search/
 61  term:                     # 针对分类术语（如标签）的 URL 配置
 62    tags: /tags/:year/:month/:slug/         # 标签的链接格式，例如 /tags/2025/03/tech/
 63
 64outputs:  # 输出格式配置
 65    home: ["HTML", "RSS", "JSON"]  # 首页生成 HTML、RSS 和 JSON 文件
 66    section: ["HTML"]  # 分类页面只生成 HTML 文件
 67    page: ["HTML"]  # 单页只生成 HTML 文件
 68
 69outputFormats:  # 自定义输出格式
 70    RSS:  # RSS 格式定义
 71        mediatype: "application/rss+xml"  # RSS 的 MIME 类型
 72        baseName: "rss"  # RSS 文件的基本名称，生成如 rss.xml
 73    JSON:  # JSON 格式定义
 74        mediatype: "application/json"  # JSON 的 MIME 类型
 75        baseName: "index"  # JSON 文件的基本名称，生成如 index.json
 76        isPlainText: true  # JSON 文件以纯文本形式输出
 77
 78services:  # 服务配置
 79    rss:  # RSS 服务设置
 80        limit: 10  # RSS 输出的文章数量限制
 81
 82params:  # 主题参数配置
 83    featuredImageField: image  # 文章特色图片的字段名
 84    rssFullContent: true  # RSS 输出完整文章内容而非摘要
 85    favicon: /img/avatar.png  # 网站图标（favicon）路径
 86
 87    sidebar:  # 侧边栏设置
 88        subtitle: 博观约取 厚积薄发  # 侧边栏副标题
 89        avatar:  # 头像配置
 90            enabled: true  # 启用头像显示
 91            local: true  # 使用本地头像文件
 92            src: /img/avatar.png  # 头像图片路径
 93
 94    mainSections:  # 主内容分区
 95        - post  # 将 "post" 设为主分区，用于首页展示
 96
 97    footer:  # 页脚设置
 98        since: 2025  # 网站起始年份
 99        #customText: ZhuYJ  # 自定义页脚文本（已注释）
100
101    dateFormat:  # 日期格式
102        published: Jan 02, 2006  # 发布日期格式
103        lastUpdated: Jan 02, 2006 15:04 MST  # 最后更新日期格式
104
105    article:  # 文章页面设置
106        math: false  # 是否启用数学公式支持
107        toc: true  # 启用目录（Table of Contents）
108        readingTime: true  # 显示阅读时间
109        license:  # 文章许可声明
110            enabled: false  # 是否启用许可声明
111            default: Licensed under CC BY-NC-SA 4.0  # 默认许可文本（已注释）
112
113    comments: # 评论系统配置
114        enabled: true  # 启用评论功能
115        provider: waline  # 使用 Waline 作为评论提供者
116        disqusjs:  # DisqusJS 配置（未启用）
117            shortname:  # DisqusJS 短名称
118            apiUrl:  # DisqusJS API URL
119            apiKey:  # DisqusJS API 密钥
120            admin:  # 管理员标识
121            adminLabel:  # 管理员标签
122        waline:  # Waline 配置
123            serverURL: https://waline.blain.top/  # Waline 服务器地址
124            lang: zh-cn  # 评论语言，中文
125            pageview: true  # 启用页面浏览量统计
126            emoji:  # 表情包配置 
127                - https://cdn.jsdelivr.net/gh/walinejs/emojis/weibo  # 表情包路径
128            requiredMeta:  # 必填字段
129                - name  # 姓名
130                - email  # 邮箱
131            locale:  # 本地化设置
132                admin: 博主  # 管理员名称
133                placeholder: 🎉留下你的脚印.  # 输入框占位符
134
135#    social:  # 社交媒体链接（已注释） 博主没用这个，根据需求打开
136#        - identifier: github  # 社交媒体标识符
137#          name: GitHub  # 显示名称
138#          url: https://github.com/CaiJimmy/hugo-theme-stack  # 链接地址
139#          params:  # 参数
140#              icon: github  # 图标名称
141#
142#        - identifier: bilibili  # 社交媒体标识符
143#          name: Bilibili  # 显示名称
144#          url: https://space.bilibili.com/450940909  # 链接地址
145#          params:  # 参数
146#              icon: bilibili  # 图标名称
147
148    widgets: # 右侧小部件配置
149        homepage:  # 首页小部件
150            - type: search  # 搜索小部件
151            - type: archives  # 归档小部件
152              params:  # 参数
153                  limit: 5  # 显示条目限制
154            - type: categories  # 分类小部件
155              params:  # 参数
156                  limit: 10  # 显示条目限制
157            - type: tag-cloud  # 标签云小部件
158              params:  # 参数
159                  limit: 10  # 显示条目限制
160        page:  # 单页小部件
161            - type: toc  # 目录小部件
162
163    defaultImage:  # 默认图片设置
164        opengraph:  # Open Graph 默认图片
165            enabled: false  # 是否启用
166            local: false  # 是否使用本地文件
167            src:  # 图片路径
168
169    colorScheme:  # 颜色主题设置
170        toggle: true  # 显示主题切换按钮
171        default: auto  # 默认主题（auto、light、dark）
172
173    imageProcessing:  # 图片处理设置
174        cover:  # 封面图片处理
175            enabled: true  # 启用处理
176        content:  # 内容图片处理
177            enabled: true  # 启用处理
178
179menu:  # 自定义菜单
180    main:  # 主菜单   下面定义了主页/关于/文章收藏/文档收藏/分类/搜索/rss 7个子页面属性
181        - identifier: home  # 菜单项标识符
182          name: 主页  # 显示名称
183          url: /post  # 链接地址
184          weight: -100  # 排序权重，越小越靠前
185          params:  # 参数
186              newTab: false  # 是否在新标签页打开
187              icon: home  # 图标名称
188
189        - identifier: about  # 菜单项标识符
190          name: 关于博主  # 显示名称
191          url: /about  # 链接地址
192          weight: -90  # 排序权重
193          params:  # 参数
194              newTab: false  # 是否在新标签页打开
195              icon: about  # 图标名称
196
197        - identifier: article  # 菜单项标识符
198          name: 文章收藏  # 显示名称
199          url: /articles  # 链接地址
200          weight: -80  # 排序权重
201          params:  # 参数
202              newTab: false  # 是否在新标签页打开
203              icon: article  # 图标名称
204
205        - identifier: doc  # 菜单项标识符
206          name: 文档收藏  # 显示名称
207          url: /doc/  # 链接地址
208          weight: -70  # 排序权重
209          params:  # 参数
210              newTab: false  # 是否在新标签页打开
211              icon: doc  # 图标名称
212
213        - identifier: categories  # 菜单项标识符
214          name: 分类  # 显示名称
215          url: /categories/  # 链接地址
216          weight: -60  # 排序权重
217          params:  # 参数
218              newTab: false  # 是否在新标签页打开
219              icon: categories  # 图标名称
220
221        - identifier: search  # 菜单项标识符
222          name: 搜索  # 显示名称
223          url: /search/  # 链接地址
224          weight: -50  # 排序权重
225          params:  # 参数
226              newTab: false  # 是否在新标签页打开
227              icon: search  # 图标名称
228
229        - identifier: rss  # 菜单项标识符
230          name: rss  # 显示名称
231          url: /rss.xml  # 链接地址
232          weight: -40  # 排序权重
233          params:  # 参数
234              newTab: true  # 在新标签页打开
235              icon: rss  # 图标名称
236
237related:  # 相关文章设置
238    includeNewer: true  # 包括较新的文章
239    threshold: 60  # 相关性阈值
240    toLower: false  # 是否转换为小写
241    indices:  # 相关性索引
242        - name: tags  # 标签索引
243          weight: 100  # 权重
244        - name: categories  # 分类索引
245          weight: 200  # 权重
246
247markup:  # 标记渲染设置
248    goldmark:  # Goldmark 渲染器配置
249        renderer:  # 渲染选项
250            unsafe: true  # 允许不安全的 HTML
251    tableOfContents:  # 目录设置
252        endLevel: 4  # 目录结束级别
253        ordered: true  # 是否有序
254        startLevel: 1  # 目录起始级别
255    highlight:  # 代码高亮设置
256        noClasses: false  # 是否禁用 CSS 类
257        codeFences: true  # 启用代码块
258        guessSyntax: true  # 猜测语法
259        lineNoStart: 1  # 行号起始值
260        lineNos: true  # 显示行号
261        lineNumbersInTable: false  # 行号是否在表格中
262        tabWidth: 4  # 制表符宽度

添加主题（stack主题为例）：

1git init
2git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack
3echo 'theme = "hugo-theme-stack"' >> hugo.yaml

创建一篇测试文章：

1hugo new content/posts/test-post.md

编辑 content/posts/test-post.md，将 draft: true 改为 draft: false否则重启hugo server不会更新当前文章;

启动本地服务器：

1hugo server

在浏览器访问 http://localhost:1313，即可看到你的博客。

界面美化部分参考:https://www.tomlife.top/docs/2025/03/hugo-doc/

waline评论区自建参考:https://www.tomlife.top/posts/2025/03/hugo-build-waline/

Hugo 常用命令参考

需要修改端口,或者链接不使用端口可以查看hugo server –help帮助或留言博主.

命令说明示例用法
hugo生成静态站点，输出到public/ 目录hugo --minify
hugo server启动开发服务器，默认端口 1313，实时预览站点hugo server --bind 0.0.0.0
hugo new创建新内容文件（如文章或页面）hugo new post/my-post.md
hugo version显示当前 Hugo 版本信息hugo version
hugo mod管理 Hugo Modules（模块化主题或依赖）hugo mod init github.com/user/repo
hugo config显示当前配置信息hugo config
hugo env显示 Hugo 环境信息（如版本、Go 版本）hugo env
hugo list列出内容文件（如草稿、未来文章）hugo list drafts
hugo check检查内容文件的完整性hugo check
hugo --help显示 Hugo 命令帮助信息hugo --help
Hugo
Licensed under CC BY-NC-SA 4.0
© 2025 ZhuYJ-开发、创业
使用 Hugo 构建
主题 Stack 由 Jimmy 设计
发表了 8 篇文章 · 总计 11.52k 字
本站已稳定运行 0 天 00 小时 00 分 00 秒