2026-03-02 博客 hugo-teek +2 安装教程使用指南 2139 字 9 分钟 -- 次

部署与使用Hugo-Teek

最后更新于: 2026-03-02 04:47:45

🎉 项目简介

Hugo-Teek 是一款基于 VitePress Teek 主题移植的 Hugo 静态网站主题，专为技术博客和文档站点设计。它保留了 VitePress Teek 的精美设计，同时利用 Hugo 的极速构建能力，为技术博客、文档库、知识管理系统提供完整的解决方案。

✨ 核心特性

🎨 设计特性

精美界面：VitePress Teek 风格设计
响应式布局：完美适配桌面/平板/移动端
暗色模式：自动切换浅色/暗色主题
三栏布局：侧边栏 + 内容 + 目录

⚡ 性能特性

极速构建：基于 Hugo 引擎
本地搜索：FlexSearch 离线全文搜索
懒加载：图片按需加载
热重载：开发时实时预览

🛠️ 功能特性

评论系统：Twikoo 评论支持
数据统计：百度/Umami/不蒜子
代码高亮：Monokai 风格 + 复制按钮
VitePress 语法：自动转换容器语法

📋 环境要求

在开始之前，请确保您的系统满足以下要求：

必需依赖🔴 推荐环境🟢

11️⃣ Hugo Extended v0.150.0+
22️⃣ Go v1.21+
33️⃣ Git

11️⃣ Node.js 18+ （用于管理后台）
22️⃣ Make （用于执行构建命令）
33️⃣ Docker （可选，用于容器化部署）

检查环境

检查 Hugo 版本🔍 检查 Go 版本🔍 检查 Git🔍

1hugo version
2# 应显示 Hugo Extended 版本

1go version
2# 应显示 go1.21 或更高版本

1git --version

🚀 安装步骤

1️⃣ 克隆项目

🔗 HTTPS 方式

步骤 1 - 克隆➡️ 步骤 2 - 进入目录🎉

1git clone https://cnb.cool/yuwen-gueen/hugo-teeker-theme.git

1cd hugo-teeker-theme

🔐 SSH 方式

步骤 1 - 克隆➡️ 步骤 2 - 进入目录🎉

1git clone git@cnb.cool:yuwen-gueen/hugo-teeker-theme.git

1cd hugo-teeker-theme

2️⃣ 安装构建工具

Linux/Mac🔧 Windows🔧 Linux/Mac 启动后台配置中心🎛️ Linux/Mac 后台配置中心说明🎛️

1make install-tools

1# 使用 PowerShell 执行
2.\bin\windows\check-and-install.bat

1sh bin/linux/start-admin.sh

1执行命令启动后台配置中心
2启动后访问: http://localhost:5173/admin
3用于图形化配置博客各项参数

3️⃣ 启动开发服务器

1make dev

1包含搜索功能、配置中心、内容监听
2访问: http://localhost:9090

1make quick

1跳过预生成和搜索索引，快速预览

1# 在项目路径中，找到以下路径，双击管理员运行start.bat
2bin\windows\start.bat

1到项目路径 bin\windows\ 目录下
2右键以管理员身份运行 start.bat
3需要重启项目时也可双击管理员运行

1# 双击管理员运行
2bin\windows\start-admin.bat

1make dev-admin

1方式1：到 bin\windows\ 目录下右键管理员运行 start-admin.bat
2方式2：在项目根目录执行 make dev-admin 命令
3启动后访问: http://localhost:6173/admin
4用于图形化配置博客各项参数

⚙️ 配置文件说明

项目采用分层配置结构，便于管理和切换主题：

核心配置📄 主题配置📄 插件配置📄

1# hugo-teek-site/config/_default/hugo.toml
2baseURL = "https://wiki.xxdevops.cn/" # 站点URL
3title = "你的站点名称"
4theme = "hugo-teek"
5languageCode = "zh-CN"

1# hugo-teek-site/config/themes/hugo-teek/params.toml
2[search]
3    enabled = true
4    provider = "flexsearch"
5
6[heroBg]
7    enabled = true
8    autoPlay = true

1# hugo-teek-site/config/teek-plugins/site.toml
2description = "站点描述"
3keywords = ["博客", "技术", "Hugo"]
4siteStartDate = "2025-01-01"

配置合并机制

项目使用智能配置合并系统，执行 make dev 时会自动：

合并 teek-plugins/ 和 themes/{theme}/ 下的配置
生成统一的 config/_default/params.toml
根据主题配置自动启用/禁用功能

📝 内容创作

文档表头格式

完整模板📋 模板说明📝

 1---
 2categories:
 3    - 博客
 4coverImg: https://mu.baimu.live/
 5date: "2025-11-27T21:20:33+08:00"
 6description: "基础 Markdown 语法示例\U0001F60D"
 7draft: false
 8featured: true
 9tags:
10    - hugo-teek
11title: 基础MD语法
12url: /hobby/jichumdyufa
13weight: 2
14---

 1---
 2categories:
 3    - 博客 # 设置文章分类
 4coverImg: https://mu.baimu.live/ # 设置文章封面
 5date: "2025-11-27T21:20:33+08:00" # 设置文章发布时间
 6description: "基础 Markdown 语法示例\U0001F60D" # 设置文章描述
 7draft: false # 是否草稿，草稿不发布
 8featured: true # 是否推荐，推荐会显示在首页
 9tags:
10    - hugo-teek # 设置文章标签02
11    - 教程 # 设置文章标签02
12    - 基础MD语法 # 设置文章标签03
13title: 基础MD语法 # 设置文章标题
14url: /hobby/jichumdyufa # 设置文章URL，建议使用小写字母和短横线分隔
15weight: 2 # 设置文章排序权重，数字越小越靠前
16---

内容目录结构

1hugo-teek-site/content/
2├── _settings/          # 设置页面
3├── about/              # 关于页面
4├── docs/               # 文档内容
5│   ├── hugo-teek默认文档/
6│   └── 40.专题/
7├── posts/              # 博客文章
8├── friends.md          # 友链页面
9└── archives.md         # 归档页面

🎨 主题切换

项目支持多主题切换，目前内置两款主题：

hugo-teek 主题🎨 hugo-simple 主题🎨

1# hugo-teek-site/config/_default/hugo.toml
2theme = "hugo-teek"
3# 功能丰富，适合文档库和博客

1# hugo-teek-site/config/_default/hugo.toml
2theme = "hugo-simple"
3# 简洁轻量，适合个人博客

切换主题后执行：

1make dev
2# 系统会自动检测主题并加载对应配置

🔍 搜索功能

搜索功能基于 FlexSearch，提供极速离线全文搜索体验。

启用搜索

启用搜索✅ 禁用搜索❌

1# config/themes/hugo-teek/params.toml
2[search]
3    enabled = true
4    provider = "flexsearch"

1# config/themes/hugo-teek/params.toml
2[search]
3    enabled = false

生成搜索索引

1# 开发模式会自动生成
2make dev
3
4# 手动生成搜索索引
5make gen-search-index

💬 评论系统

内置 Twikoo 评论系统，支持多种部署方式。

配置评论

1# config/teek-plugins/services.toml
2[comment]
3    enabled = true
4    type = "twikoo"
5    envId = "你的 Twikoo 环境 ID"

Twikoo 部署方式

Vercel 部署☁️ Docker 部署🐳 云函数部署⚡

11️⃣ Fork Twikoo 仓库
22️⃣ 在 Vercel 导入并部署
33️⃣ 创建 MongoDB 数据库
44️⃣ 配置环境变量

11️⃣ 使用 Docker Compose 部署
22️⃣ 内置 MongoDB，一键启动

11️⃣ 腾讯云云函数
22️⃣ 阿里云函数计算

📊 数据统计

支持多种统计方案，可同时启用多个：

百度统计📈 Umami📈 不蒜子📈

1    enabled = true
2    token = "你的百度统计 token"

1    enabled = true
2    websiteId = "你的网站 ID"
3    src = "https://your-umami.com/script.js"

1    enabled = true

🏗️ 构建部署

本地构建

标准构建🏗️ 优化构建⚡ 极速构建🚀

1make build

1make build-optimized

1make build-fastest

标准构建说明🏗️ 优化构建说明⚡ 极速构建说明🚀

1完整构建，包含搜索索引
2输出目录: hugo-teek-site/public/

1标准构建（含优化后的搜索索引，~60秒）

1跳过非必要步骤，无搜索（~10秒）

Docker 构建

构建镜像🐳 运行容器🐳 推送镜像🐳

1make docker-build-ci

1make docker-run

1make docker-push

CI/CD 部署

项目提供完整的 CI/CD 支持，详见 docker/README.md 和 CI_CD_GUIDE.md。

🛠️ 常用命令

开发命令

命令	说明
`make dev`	启动完整开发环境
`make quick`	快速启动（跳过数据生成）
`make dev-admin`	启动管理后台

数据生成命令

命令	说明
`make fix-frontmatter`	修复缺失的 Front Matter
`make gen-permalink`	生成 SEO 友好的 permalink
`make gen-sidebar-order`	生成侧边栏排序数据
`make gen-index`	生成索引页
`make gen-search-index`	生成搜索索引

构建命令

命令	说明
`make build`	构建生产版本
`make build-optimized`	优化构建（推荐）
`make build-fastest`	极速构建
`make clean`	清理构建文件

🔧 故障排除

常见问题

端口被占用❌ 搜索不工作❌ 样式丢失❌

1# 错误：端口 9090 已被占用
2# 解决：make dev 会自动清理端口
3# 或手动指定端口：
4make dev FRONTEND_PORT=8080

1# 检查搜索配置是否启用
2# 重新生成搜索索引：
3make gen-search-index

1# 清理并重新构建：
2make clean
3make dev

获取帮助

📖 文档：https://wiki.xxdevops.cn
🐛 Issues：cnb Issues
💬 讨论：加入Hugo-Teek交流群

🌟 如果这个项目对你有帮助，请给个 Star！

📄 许可证

本项目采用 MIT License 开源许可证。

本项目开发者 ❤️ by 余温Gueen
本项目贡献者 ❤️ by 白木
本项目贡献者 ❤️ by one

本项目基于 Hugo 框架开发，感谢所有贡献者的努力！

📡

👤 作者: 余温Gueen

🔗 链接: https://wiki.xxdevops.cn/hobby/anzhuang-shiyong

🌐 版权: 本站文章除特别声明外，均采用 CC BY-NC-SA 4.0 协议，转载请注明来自余温Gueen Blog！

推荐使用微信支付

推荐使用支付宝

下一篇基础MD语法