hugo

Hugo 静态站点生成器

状态：已可用于生产环境 | 最后更新：2026-08-03 最新版本：[email protected]+extended | 构建速度：<100ms

---

快速入门（5 分钟）

1. 安装 Hugo Extended

重要：除非你确定不需要 SCSS/Sass 支持，否则请始终安装 Hugo Extended 版本（而非 Standard）。大多数主题都需要 Extended。

# macOS
brew install hugo

# Linux (Ubuntu/Debian)
wget https://github.com/gohugoio/hugo/releases/download/v0.164.0/hugo_extended_0.164.0_linux-amd64.deb
sudo dpkg -i hugo_extended_0.164.0_linux-amd64.deb

# Verify Extended edition
hugo version  # Should show "+extended"

原因：

• Hugo Extended 包含 SCSS/Sass 处理功能
• 大多数热门主题（PaperMod、Academic、Docsy）都需要 Extended
• Standard 版本会报错：“未启用 SCSS 支持”
• Extended 没有缺点（速度相同，功能相同且更多）

2. 创建新的 Hugo 站点

# Use YAML format (not TOML) for better CMS compatibility
hugo new site my-blog --format yaml

# Initialize Git
cd my-blog
git init

# Add PaperMod theme (recommended for blogs)
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

重要：

• 使用 --format yaml 创建 hugo.yaml（而非 hugo.toml）
• Sveltia CMS 需要 YAML，TinaCMS 也推荐使用 YAML
• Sveltia CMS beta 中的 TOML 存在已知错误
• 稍后克隆时，Git 子模块需要 --recursive 标志

3. 配置并构建

# hugo.yaml - Minimal working configuration
baseURL: "https://example.com/"
title: "My Hugo Blog"
theme: "PaperMod"
languageCode: "en-us"
enableRobotsTXT: true

params:
  ShowReadingTime: true
  ShowShareButtons: true
  defaultTheme: auto  # Supports dark/light/auto

# Create first post
hugo new content posts/first-post.md

# Run development server (with live reload)
hugo server

# Build for production
hugo --minify

# Output is in public/ directory

---

关键规则

始终做到

✅ 安装 Hugo Extended（而非 Standard）——主题需要它来支持 SCSS/Sass
✅ 使用 YAML 配置（--format yaml）——比 TOML 具有更好的 CMS 兼容性
✅ 将主题添加为 Git 子模块——便于更新和版本控制
✅ 设置正确的 baseURL——避免部署时资源链接失效
✅ 在 CI/CD 中固定 Hugo 版本——避免本地与部署环境之间出现版本不匹配错误
✅ 将 public/ 添加到 .gitignore——不应提交构建输出
✅ 使用 draft: false——草稿不会出现在生产构建中
✅ 使用 --recursive 标志克隆——确保获取主题子模块
✅ 为图片使用相对路径——使用 /images/photo.jpg，而非 ../images/photo.jpg
✅ 部署前测试构建——使用 hugo --minify 在本地捕获错误

绝不要做

❌ 不要安装 Hugo Standard——大多数主题都需要 Extended 版本
❌ 不要在 Sveltia CMS 中使用 TOML 配置——存在已知错误，请改用 YAML
❌ 不要提交 public/ 目录——它是生成的输出，不是源代码
❌ 不要使用不同的 Hugo 版本——本地与 CI/CD 版本不匹配会导致错误
❌ 不要忘记 submodules: recursive——主题将无法在 CI/CD 中加载
❌ 不要硬编码生产环境 URL——使用 -b $CF_PAGES_URL 或环境配置
❌ 不要推送 resources/_gen/——这是生成的资源，应添加到 .gitignore
❌ 不要随意使用未来日期——文章要等到日期到达后才会发布
❌ 不要遗漏 .hugo_build.lock——将其添加到 .gitignore
❌ 不要混用 YAML 和 TOML——整个项目应始终使用同一种格式

---

防范最常见的 5 个错误

此指南可防范15 个已记录的错误。以下是其中最常见的 5 个：

错误 #1：版本不匹配（Hugo 与 Hugo Extended）

错误：Error: SCSS support not enabled 防范方法：始终安装 Hugo Extended 版本。使用 hugo version | grep extended 验证 参见：references/error-catalog.md，查看完整错误列表

错误 #2：baseURL 配置错误

错误：CSS/JS/图片链接失效，所有资源均返回 404 防范方法：使用特定环境的配置或构建标志：hugo -b $CF_PAGES_URL 参见：references/error-catalog.md #2

错误 #3：找不到主题

错误：Error: module "PaperMod" not found，站点空白 防范方法：在 hugo.yaml 中设置 theme: "PaperMod"，并运行 git submodule update --init --recursive 参见：references/error-catalog.md #6

错误 #4：Hugo 版本不匹配（本地与部署环境）

错误：功能在本地可用，但在 CI/CD 中失败，反之亦然 防范方法：在所有环境中固定 Hugo 版本（CI/CD、本地文档；如果使用 npm，也包括 package.json） 参见：references/error-catalog.md #4

错误 #5：CI/CD 中未找到 Git 子模块

错误：主题在本地正常，但在 CI/CD 中无法运行，部署后网站空白 预防：在 GitHub Actions 的 checkout 操作中添加 submodules: recursive 参见：references/error-catalog.md #11

完整错误目录（全部 15 个错误）：参见 references/error-catalog.md

---

使用随附资源

参考资料（references/）：

• setup-guide.md - Hugo 完整设置指南（安装、主题、部署）
• error-catalog.md - 全部 15 个常见 Hugo 错误及其解决方案和预防措施
• common-patterns.md - 最佳实践和模式（分类法、内容组织、多语言）
• cms-integration.md - Sveltia CMS 集成指南及配置
• tailwind-integration.md - Tailwind CSS 与 Hugo Pipes 集成
• advanced-topics.md - Hugo 高级功能（模块、数据文件、国际化）

模板（templates/）

可直接复制使用的完整生产级 Hugo 项目：

• templates/hugo-blog/ - 使用 PaperMod 主题的博客

  • 深色／浅色模式、搜索、标签、归档
  • 预先配置 Sveltia CMS
  • 包含用于 Workers 部署的 wrangler.jsonc
  • 包含 GitHub Actions 工作流
  • 适用场景：构建个人博客、公司博客或新闻网站

• templates/hugo-docs/ - 使用 Hugo Book 主题的文档网站

  • 嵌套导航、搜索、面包屑导航
  • 使用 Sveltia CMS 编辑文档
  • 适用场景：创建技术文档、知识库、API 文档

• templates/hugo-landing/ - 使用自定义布局的落地页

  • Hero、功能介绍、用户评价、CTA 区块
  • 不依赖主题（自定义布局）
  • 针对转化进行优化
  • 适用场景：构建营销网站、产品页面、作品集

• templates/minimal-starter/ - 精简入门模板

  • 无主题，提供干净的起点
  • 添加主题的设置指南
  • 最精简的配置
  • 适用场景：从头开始并完全掌控项目

使用模板快速开始：

cp -r templates/hugo-blog/ my-new-blog/
cd my-new-blog
git submodule update --init --recursive
hugo server

参考资料（references/）

按需加载的详细指南：

• references/setup-guide.md - 完整的 7 步设置流程

  • 安装和验证
  • 项目脚手架
  • 主题安装
  • 配置选项
  • 创建内容
  • 构建和开发
  • 部署到 Cloudflare Workers
  • 加载时机：从头开始设置新的 Hugo 项目时

• references/cms-integration.md - 无头 CMS 集成

  • Sveltia CMS 设置（推荐）——5 分钟
  • 生产环境的 OAuth 配置
  • TinaCMS 设置（不推荐）
  • 比较和故障排除
  • 加载时机：为 Hugo 网站添加内容管理功能时

• references/tailwind-integration.md - Tailwind CSS v4 集成

  • Hugo Pipes + PostCSS 设置
  • 深色模式实现（纯 CSS 和 Alpine.js）
  • Typography 和 Forms 插件
  • 生产环境优化
  • 常见问题及解决方案
  • 加载时机：将 Tailwind CSS 与 Hugo 集成时

• references/common-patterns.md - 7 种常见项目模式

  • 使用 PaperMod 的博客
  • 使用 Hugo Book 的文档网站
  • 落地页
  • 多语言网站
  • 作品集网站
  • 电子商务（静态）
  • 新闻通讯／博客
  • 加载时机：为特定使用场景选择架构时

• references/advanced-topics.md - Hugo 高级功能

  • 自定义短代码
  • 图像处理
  • 自定义分类法
  • 数据文件（JSON/YAML/CSV）
  • 页面包
  • 模板覆盖
  • Hugo Modules
  • 加载时机：用户需要高级自定义功能时

• references/error-catalog.md - 全部 15 个已记录的错误

  • 完整的错误消息和解决方案
  • 预防策略
  • 引用官方资料
  • 故障排除指南
  • 加载时机：调试问题或预防已知错误时

---

常见使用场景

用例 1：个人博客

模板：templates/hugo-blog/ 主题：PaperMod 部署时间：10 分钟 功能：搜索、标签、深色模式、RSS、Sveltia CMS

cp -r templates/hugo-blog/ my-blog/
cd my-blog
git submodule update --init --recursive
hugo new content posts/first-post.md
hugo server

参见 references/common-patterns.md → 模式 1

用例 2：技术文档

模板：templates/hugo-docs/ 主题：Hugo Book 部署时间：10 分钟 功能：嵌套导航、搜索、面包屑、多语言

cp -r templates/hugo-docs/ docs-site/
cd docs-site
git submodule update --init --recursive
hugo new content docs/getting-started/installation.md
hugo server

参见 references/common-patterns.md → 模式 2

用例 3：落地页

模板：templates/hugo-landing/ 主题：无（自定义布局） 部署时间：15 分钟 功能：主视觉区、功能介绍、用户评价、行动号召、联系表单

cp -r templates/hugo-landing/ landing/
cd landing
hugo server

参见 references/common-patterns.md → 模式 3

用例 4：使用 Tailwind CSS v4 的博客

模板：从 templates/minimal-starter/ 开始 集成：按照 references/tailwind-integration.md 操作 设置时间：30 分钟 功能：自定义设计、实用优先的 CSS、深色模式

cp -r templates/minimal-starter/ tailwind-blog/
cd tailwind-blog
# Follow references/tailwind-integration.md for setup

参见 references/tailwind-integration.md → 快速开始

用例 5：多语言文档

模板：templates/hugo-docs/ 模式：多语言 设置时间：20 分钟 功能：语言切换器、翻译后的内容、按语言设置菜单

参见 references/common-patterns.md → 模式 4

---

Cloudflare Workers 部署

快速部署

1. 创建 wrangler.jsonc：

{
  "name": "my-hugo-site",
  "compatibility_date": "2025-01-29",
  "assets": {
    "directory": "./public",
    "html_handling": "auto-trailing-slash",
    "not_found_handling": "404-page"
  }
}

2. 部署：

hugo --minify
bunx wrangler deploy

**完整部署指南：**参见 references/setup-guide.md → 步骤 7

---

何时加载详细参考资料

在以下情况加载 references/setup-guide.md：

• 用户需要完整的 7 步设置流程
• 用户询问配置选项
• 用户需要详细的安装说明
• 用户询问目录结构
• 用户需要 GitHub Actions 工作流

在以下情况加载 references/cms-integration.md：

• 用户想为 Hugo 站点添加 CMS
• 用户询问 Sveltia CMS 设置
• 用户询问 TinaCMS（请提醒用户不推荐使用）
• 用户需要 OAuth 配置
• 用户询问内容管理

在以下情况加载 references/tailwind-integration.md：

• 用户想集成 Tailwind CSS v4
• 用户询问 PostCSS 设置
• 用户需要实现深色模式
• 用户询问 Tailwind 插件
• 用户遇到 CSS 处理错误

在以下情况加载 references/common-patterns.md：

• 用户询问“如何构建 [博客/文档/落地页]？”
• 用户需要架构方面的指导
• 用户询问多语言站点
• 用户询问作品集站点
• 用户需要项目结构示例

在以下情况加载 references/advanced-topics.md：

• 用户询问短代码
• 用户需要图像处理
• 用户想要自定义分类法
• 用户询问数据文件
• 用户需要自定义模板

在以下情况加载 references/error-catalog.md：

• 用户遇到错误
• 用户询问故障排除
• 用户想避免已知问题
• 用户询问“有哪些错误需要留意？”
• 用户遇到部署问题

---

依赖项

必需：

• Hugo v0.159.2+（Extended 版本）- 静态站点生成器（安全最低版本：CVE-2026-35166 XSS 漏洞已在 0.159.2 中修复；最新稳定版为 0.164.0）

可选（用于部署）：

• wrangler v4.0.0+ - Cloudflare Workers 部署
• Git v2.0+ - 版本控制和主题子模块

可选（用于 CMS）：

• Sveltia CMS（最新版本）- 内容管理（基于 CDN，无需安装）

---

官方文档

• Hugo：https://gohugo.io/documentation/
• PaperMod 主题：https://github.com/adityatelange/hugo-PaperMod/wiki
• Hugo Book 主题：https://github.com/alex-shpak/hugo-book
• Sveltia CMS：https://github.com/sveltia/sveltia-cms
• Cloudflare Workers：https://developers.cloudflare.com/workers/
• Hugo 主题：https://themes.gohugo.io/

---

软件包版本（已于 2026-08-03 验证）

Hugo：v0.164.0+extended（2026 年 7 月 6 日） PaperMod：最新版本（通过 Git 子模块获取） Sveltia CMS：最新版本（通过 CDN 获取） Wrangler：v4.37.1+（v4.45.3 已发布）

---

生产环境示例

此技能基于实际测试：

• 测试站点：https://hugo-blog-test.webfonts.workers.dev
• 构建时间：24ms（20 个页面）
• 部署时间：约 21 秒
• 错误：0（已预防全部 15 个已知问题）
• 验证：✅ Hugo + PaperMod + Sveltia + Workers 已成功部署

---

完整设置检查清单

使用此检查清单验证设置：

• 已安装 Hugo Extended v0.159.2+（hugo version 显示“+extended”）
• 使用 --format yaml 创建项目（存在 hugo.yaml）
• 已安装并配置主题（通过 Git 子模块或 Hugo Module）
• 已在 hugo.yaml 中正确配置 baseURL
• .gitignore 包含 public/ 和 resources/_gen/
• 已创建示例内容，且渲染正确
• 开发服务器运行无错误（hugo server）
• 生产环境构建成功（hugo --minify）
• 已为 Workers 配置 wrangler.jsonc（如需部署）
• 已配置 Sveltia CMS（如使用 CMS）
• 已配置 GitHub Actions 工作流（如使用 CI/CD）
• 已成功部署（如部署到 Workers）

---

有疑问？遇到问题？

1. 查看 references/error-catalog.md，了解所有 15 个已记录的错误及其解决方案
2. 验证设置流程中的所有步骤
3. 使用 templates/ 目录中的合适模板
4. 加载相关参考指南，了解详细信息
5. 查看官方文档：https://gohugo.io/documentation/

---

此技能提供可用于生产环境的 Hugo 设置，且不会产生错误。所有 15 个常见问题均已记录并预防。