hugo

Hugo 静态网站生成器

状态：已可用于生产环境 最后更新：2025-11-04 依赖项：无（Hugo 是独立二进制文件） 最新版本：[email protected]+extended、PaperMod@latest、Sveltia CMS@latest

---

快速开始（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.152.2/hugo_extended_0.152.2_linux-amd64.deb
sudo dpkg -i hugo_extended_0.152.2_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

---

7 步设置流程

第 1 步：安装和验证

使用以下任一方法安装 Hugo Extended：

方法 1：Homebrew（macOS/Linux） ✅ 推荐

brew install hugo

方法 2：下载二进制文件（Linux）

# Check latest version: https://github.com/gohugoio/hugo/releases
VERSION="0.152.2"
wget https://github.com/gohugoio/hugo/releases/download/v${VERSION}/hugo_extended_${VERSION}_linux-amd64.deb
sudo dpkg -i hugo_extended_${VERSION}_linux-amd64.deb

方法 3：Docker

docker run --rm -it -v $(pwd):/src klakegg/hugo:ext-alpine

方法 4：NPM 封装程序（不推荐，版本可能滞后）

npm install -g hugo-bin

验证：

hugo version
# Should output: hugo v0.152.2+extended
#                                ^^^^^^^^ Must show "+extended"

要点：

• SCSS/Sass 需要 Extended 版本
• 为获得最佳兼容性，版本应为 v0.149.0+
• NPM 封装程序可能落后于官方版本
• 在 CI/CD 中固定版本（见第 7 步）

第 2 步：搭建项目框架

使用 YAML 配置创建新网站：

hugo new site my-site --format yaml
cd my-site

创建的目录结构：

my-site/
├── hugo.yaml          # Configuration (YAML format)
├── archetypes/        # Content templates
│   └── default.md
├── content/           # All your content goes here
├── data/              # Data files (JSON/YAML/TOML)
├── layouts/           # Template overrides
├── static/            # Static assets (images, CSS, JS)
├── themes/            # Themes directory
└── public/            # Build output (generated, git ignore)

重要：

• 使用 --format yaml 以兼容 CMS
• 切勿将 public/ 目录提交到 Git
• 立即创建 .gitignore（见第 3 步）

第 3 步：安装主题

推荐方法：Git 子模块 ✅

# Popular themes:
# - PaperMod (blogs): https://github.com/adityatelange/hugo-PaperMod
# - Book (docs): https://github.com/alex-shpak/hugo-book
# - Academic (research): https://github.com/HugoBlox/theme-academic-cv
# - Ananke (general): https://github.com/theNewDynamic/gohugo-theme-ananke

git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

替代方法：Hugo Modules（进阶）

hugo mod init github.com/username/my-site

# In hugo.yaml:
# module:
#   imports:
#     - path: github.com/adityatelange/hugo-PaperMod

将主题添加到 hugo.yaml：

theme: "PaperMod"

使用子模块克隆项目时：

git clone --recursive https://github.com/username/my-site.git
# Or if already cloned:
git submodule update --init --recursive

要点：

• 推荐使用 Git 子模块，而非手动下载
• --depth=1 可节省空间（不包含主题历史记录）
• 克隆后务必运行 git submodule update --init --recursive
• Hugo Modules 更进阶，但无需使用 Git 子模块

第 4 步：配置

hugo.yaml——完整示例（PaperMod 博客）：

baseURL: "https://example.com/"
title: "My Hugo Blog"
theme: "PaperMod"
languageCode: "en-us"
defaultContentLanguage: "en"
enableRobotsTXT: true
buildDrafts: false
buildFuture: false
buildExpired: false
enableEmoji: true

minify:
  disableXML: true
  minifyOutput: true

params:
  env: production
  title: "My Hugo Blog"
  description: "A blog built with Hugo and PaperMod"
  author: "Your Name"
  ShowReadingTime: true
  ShowShareButtons: true
  ShowPostNavLinks: true
  ShowBreadCrumbs: true
  ShowCodeCopyButtons: true
  defaultTheme: auto  # dark, light, auto

  socialIcons:
    - name: twitter
      url: "https://twitter.com/username"
    - name: github
      url: "https://github.com/username"

menu:
  main:
    - identifier: posts
      name: Posts
      url: /posts/
      weight: 10
    - identifier: about
      name: About
      url: /about/
      weight: 20

outputs:
  home:
    - HTML
    - RSS
    - JSON  # Required for search

配置格式：

• YAML（推荐）：hugo.yaml——与 CMS 的兼容性更好
• TOML（旧版）：hugo.toml——默认格式，但与 Sveltia CMS 配合时存在问题
• JSON：hugo.json——很少使用

特定环境配置：

config/
├── _default/
│   └── hugo.yaml
├── production/
│   └── hugo.yaml  # Overrides for production
└── development/
    └── hugo.yaml  # Overrides for local dev

第 5 步：创建内容

使用 Hugo CLI 创建内容：

# Blog post
hugo new content posts/my-first-post.md

# Page
hugo new content about.md

# Nested documentation
hugo new content docs/getting-started/installation.md

Frontmatter 格式（推荐使用 YAML）：

---
title: "My First Post"
date: 2025-11-04T10:00:00+11:00
draft: false
tags: ["hugo", "blog"]
categories: ["General"]
description: "A brief description for SEO"
cover:
  image: "/images/cover.jpg"
  alt: "Cover image"
---

# Post content starts here

This is my first Hugo blog post!

TOML Frontmatter（仅供参考）：

+++
title = "My First Post"
date = 2025-11-04T10:00:00+11:00
draft = false
tags = ["hugo", "blog"]
+++

要点：

• YAML frontmatter 使用 --- 作为分隔符
• TOML frontmatter 使用 +++ 作为分隔符
• 要让文章在生产环境中显示，必须设置 draft: false
• date 为未来时间时，文章不会发布（除非使用 --buildFuture 标志）
• 内容应写在 frontmatter 结束分隔符之后

第 6 步：构建和开发

开发服务器（支持实时重新加载）：

# Start server
hugo server

# With drafts visible
hugo server --buildDrafts

# With future-dated posts
hugo server --buildFuture

# Bind to specific port
hugo server --port 1314

# Access at: http://localhost:1313

生产环境构建：

# Basic build
hugo

# With minification (recommended)
hugo --minify

# With specific baseURL (for deployment)
hugo --minify --baseURL https://example.com

# Or use environment variable
hugo --minify -b $CF_PAGES_URL

构建输出：

• 所有生成的文件都会写入 public/ 目录
• 典型构建时间：小型网站不到 100 毫秒，1000+ 个页面的网站不到 5 秒
• Hugo 是速度最快的静态网站生成器

要点：

• 开发服务器支持实时重新加载（HMR）
• 生产环境构建应使用 --minify
• 切勿提交 public/ 目录
• 构建速度极快（Hugo 使用 Go 编写）

第 7 步：部署到 Cloudflare Workers

创建 wrangler.jsonc：

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

手动部署：

# Build site
hugo --minify

# Deploy to Workers
npx wrangler deploy

GitHub Actions（自动化）：

创建 .github/workflows/deploy.yml：

name: Deploy to Cloudflare Workers

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive  # Important for theme submodules!

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.152.2'
          extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy to Cloudflare Workers
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

要点：

• assets.directory 必须为 "./public"（Hugo 的输出目录）
• html_handling: "auto-trailing-slash" 用于处理 Hugo 的 URL 结构
• not_found_handling: "404-page" 用于提供 Hugo 的 404.html
• 始终在 CI/CD 中固定 Hugo 版本（避免版本不匹配错误）
• 使用 submodules: recursive 获取主题子模块

---

关键规则

务必做到

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

---

已知问题预防

此技能可预防 9 个已记录的问题：

问题 #1：版本不匹配（Hugo 与 Hugo Extended）

错误：Error: SCSS support not enabled 来源：https://gohugo.io/troubleshooting/faq/#i-get-this-feature-is-not-available-in-your-current-hugo-version 发生原因：主题需要 SCSS/Sass 处理功能，但 Hugo Standard 不包含此功能 预防方法：始终安装 Hugo Extended 版本。使用 hugo version | grep extended 验证

问题 #2：baseURL 配置错误

错误：CSS/JS/图片链接失效，所有资源均返回 404 来源：Hugo 文档、Cloudflare Pages 指南 发生原因：配置中的 baseURL 与部署 URL 不匹配 预防方法：

• 使用特定环境的配置（config/production/hugo.yaml）
• 或使用构建标志：hugo -b $CF_PAGES_URL
• 或在构建前于 hugo.yaml 中设置正确的 baseURL

问题 #3：TOML 与 YAML 配置混淆

错误：Sveltia CMS 无法解析 frontmatter，或配置无法加载 来源：Sveltia CMS 文档、社区报告 发生原因：混用 TOML 和 YAML，或将 TOML 与 Sveltia CMS 搭配使用（存在错误） 预防方法：统一使用 YAML 格式。使用 --format yaml 标志创建站点

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

错误：功能在本地正常，但在 CI/CD 中失败，反之亦然 来源：GitHub Actions hugo-setup、Cloudflare Pages 文档 发生原因：不同的 Hugo 版本具有不同的功能和错误 预防方法：

• 在 hugo.yaml 元数据或 README 中固定 Hugo 版本
• 在 Cloudflare Pages 中设置 HUGO_VERSION
• 在 GitHub Actions 中使用 hugo-version: '0.152.2'

Issue #5：内容 Frontmatter 格式错误

错误：内容文件无法渲染，构建因解析错误而失败 来源：Hugo 内容管理文档 原因：分隔符错误（--- 与 +++ 混用）、YAML/TOML 语法无效 预防措施：

• YAML：使用 --- 分隔符
• TOML：使用 +++ 分隔符
• 使用 Sveltia CMS 或 YAML linter 验证 frontmatter

Issue #6：找不到主题错误

错误：Error: module "PaperMod" not found，网站显示空白 来源：Hugo 主题文档 原因：未安装主题、未在配置中设置 theme，或未初始化 Git 子模块 预防措施：

• 在 hugo.yaml 中设置 theme: "PaperMod"
• 使用 git submodule add 安装主题
• 克隆后始终运行 git submodule update --init --recursive

Issue #7：日期时间偏移问题

错误：内容在本地可见，但部署后的网站上缺失 来源：Hugo 日期处理文档 原因：未来日期的文章在本地发布（使用 --buildFuture），但在生产环境中未发布 预防措施：

• 在 frontmatter 中使用当前日期或过去的日期
• 或在生产构建中添加 --buildFuture 标志
• 检查 frontmatter 中的 date 字段

Issue #8：Public 文件夹冲突

错误：网站内容过时，public/ 中出现 Git 冲突 来源：Hugo 项目结构最佳实践 原因：提交了 public/ 目录，而它本应仅作为构建输出 预防措施：

• 将 public/ 添加到 .gitignore
• 每次部署时都重新构建
• 切勿提交生成的文件

Issue #9：模块缓存问题

错误：failed to extract shortcode，模块缓存损坏 来源：Hugo 模块文档、GitHub 问题 原因：Hugo Modules 缓存损坏（使用模块而非子模块时） 预防措施：

• 运行 hugo mod clean 清除缓存
• 定期运行 hugo mod tidy
• 或使用 Git 子模块代替模块（更可靠）

---

配置文件参考

hugo.yaml（完整生产环境示例）

baseURL: "https://example.com/"
title: "My Hugo Blog"
theme: "PaperMod"
languageCode: "en-us"
defaultContentLanguage: "en"
enableRobotsTXT: true
buildDrafts: false
buildFuture: false
buildExpired: false
enableEmoji: true
pygmentsUseClasses: true
summaryLength: 30

minify:
  disableXML: true
  minifyOutput: true

params:
  env: production
  title: "My Hugo Blog"
  description: "A blog built with Hugo and PaperMod"
  keywords: [Blog, Hugo, Tech]
  author: "Your Name"
  images: ["/images/og-image.jpg"]
  DateFormat: "January 2, 2006"
  defaultTheme: auto  # dark, light, auto
  disableThemeToggle: false

  ShowReadingTime: true
  ShowShareButtons: true
  ShowPostNavLinks: true
  ShowBreadCrumbs: true
  ShowCodeCopyButtons: true
  ShowWordCount: true
  ShowRssButtonInSectionTermList: true
  UseHugoToc: true
  disableSpecial1stPost: false
  disableScrollToTop: false
  comments: false
  hidemeta: false
  hideSummary: false
  showtoc: true
  tocopen: false

  assets:
    disableHLJS: true
    disableFingerprinting: false

  label:
    text: "My Hugo Blog"
    icon: /favicon.ico
    iconHeight: 35

  homeInfoParams:
    Title: "Hi there 👋"
    Content: Welcome to my blog.

  socialIcons:
    - name: twitter
      url: "https://twitter.com/"
    - name: github
      url: "https://github.com/"
    - name: linkedin
      url: "https://linkedin.com/"
    - name: rss
      url: "/index.xml"

  cover:
    hidden: false
    hiddenInList: false
    hiddenInSingle: false

  editPost:
    URL: "https://github.com/username/repo/tree/main/content"
    Text: "Suggest Changes"
    appendFilePath: true

  fuseOpts:
    isCaseSensitive: false
    shouldSort: true
    location: 0
    distance: 1000
    threshold: 0.4
    minMatchCharLength: 0
    keys: ["title", "permalink", "summary", "content"]

menu:
  main:
    - identifier: search
      name: Search
      url: /search/
      weight: 10
    - identifier: posts
      name: Posts
      url: /posts/
      weight: 20
    - identifier: archives
      name: Archives
      url: /archives/
      weight: 30
    - identifier: tags
      name: Tags
      url: /tags/
      weight: 40
    - identifier: about
      name: About
      url: /about/
      weight: 50

outputs:
  home:
    - HTML
    - RSS
    - JSON  # Required for search functionality

这些设置的原因：

• buildDrafts: false - 防止草稿出现在生产环境中
• enableRobotsTXT: true - SEO 最佳实践
• minifyOutput: true - 减小文件体积
• defaultTheme: auto - 遵循用户的系统偏好
• JSON 输出 - 启用客户端搜索
• 社交图标 - 提升内容的可发现性

wrangler.jsonc（Cloudflare Workers）

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

这些设置的原因：

• directory: "./public" - Hugo 的构建输出目录
• html_handling: "auto-trailing-slash" - 与 Hugo 的 URL 结构相匹配
• not_found_handling: "404-page" - 提供 Hugo 自定义的 404.html

.gitignore（必备）

# Hugo
/public/
/resources/_gen/
.hugo_build.lock

# OS
.DS_Store
Thumbs.db

# Editor
.vscode/
.idea/
*.swp
*.swo

# Dependencies (if using npm for tools)
node_modules/
package-lock.json

# Logs
*.log

---

Sveltia CMS 集成（推荐）

为什么为 Hugo 选择 Sveltia CMS？

✅ Hugo 是 Sveltia 的主要用途 - 专为 Hugo 设计 ✅ 设置简单 - 只需 2 个静态文件，无需构建步骤 ✅ 无需 npm 依赖 - 只需一个 CDN 脚本 ✅ 本地后端 - 无需 Git 即可在本地测试 CMS ✅ YAML frontmatter - 完全兼容 ✅ 无安全漏洞 - 轻量且持续维护 ✅ 积极开发 - 专注于静态站点生成器

设置（5 分钟）

1. 创建管理界面 - static/admin/index.html：

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <title>Content Manager</title>
  </head>
  <body>
    <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
  </body>
</html>

2. 创建 CMS 配置 - static/admin/config.yml：

backend:
  name: git-gateway
  branch: main

local_backend: true  # Enable local testing

media_folder: "static/images/uploads"
public_folder: "/images/uploads"

collections:
  - name: "blog"
    label: "Blog Posts"
    folder: "content/posts"
    create: true
    slug: "{{slug}}"
    fields:
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Description", name: "description", widget: "string", required: false}
      - {label: "Date", name: "date", widget: "datetime"}
      - {label: "Draft", name: "draft", widget: "boolean", default: false}
      - {label: "Tags", name: "tags", widget: "list", required: false}
      - {label: "Categories", name: "categories", widget: "list", required: false}
      - {label: "Cover Image", name: "cover", widget: "object", required: false, fields: [
          {label: "Image", name: "image", widget: "image", required: false},
          {label: "Alt Text", name: "alt", widget: "string", required: false}
        ]}
      - {label: "Body", name: "body", widget: "markdown"}

  - name: "pages"
    label: "Pages"
    folder: "content"
    create: true
    slug: "{{slug}}"
    filter: {field: "type", value: "page"}
    fields:
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Date", name: "date", widget: "datetime"}
      - {label: "Type", name: "type", widget: "hidden", default: "page"}
      - {label: "Draft", name: "draft", widget: "boolean", default: false}
      - {label: "Body", name: "body", widget: "markdown"}

3. 重新构建网站：

hugo
# Admin interface now at: http://localhost:1313/admin

4. 生产环境 OAuth（用于 Git 后端）：

Sveltia CMS 需要 OAuth 来进行生产环境中的 GitHub/GitLab 身份验证。使用 Cloudflare Workers 作为 OAuth 代理：

参见随附参考文档：references/sveltia-integration-guide.md

要点：

• 构建后可通过 /admin 访问管理界面
• local_backend: true 可在无需 Git 的情况下进行本地测试
• 必须使用 YAML frontmatter 格式
• 集合映射到 Hugo 内容目录
• 媒体文件保存到 static/images/uploads

---

TinaCMS 集成（不推荐）

⚠️ 请改用 Sveltia CMS。TinaCMS 在 Hugo 上有明显的局限性：

为什么不选 TinaCMS？

❌ 仅支持 React 可视化编辑 - Hugo 使用 Go 模板，无法进行可视化编辑 ❌ 设置复杂 - 需要 Node.js 服务端或 Tina Cloud ❌ 692 个 npm 包 - 而 Sveltia 只需 1 个 CDN 脚本 ❌ 7 个安全漏洞 -（截至 2025-11-04，其中 4 个高危、3 个严重） ❌ 专注于 React/Next.js - Hugo 是次要使用场景 ❌ 仅支持 YAML - 与 Sveltia 有相同的限制，却没有其优势

如果必须使用 TinaCMS

仅在以下情况下考虑 TinaCMS：

• 已在使用 Tina Cloud
• 有可用的 React 专业知识
• 需要 Tina 专属功能

参见附带的参考资料：references/tinacms-integration-guide.md（警告：不推荐）

---

Tailwind CSS v4 集成

Hugo 通过 Hugo Pipes 和 Tailwind CLI 支持 Tailwind CSS v4。这种方式与基于 Vite 的 React 项目有根本区别。

何时使用 Tailwind，何时使用主题

在 Hugo 中使用 Tailwind 的情况：

• 构建不依赖主题的自定义设计
• 需要实用类优先的 CSS 工作流
• 希望完全掌控样式
• 相较于 SCSS/Sass 更偏好 Tailwind

使用主题（PaperMod、Book 等）的情况：

• 希望采用经过验证、可用于生产环境的设计
• 需要快速设置，无需编写自定义 CSS
• 满意于主题提供的自定义选项
• 不需要像素级精准的自定义设计

与 Vite + React 的主要区别

重要： 不要尝试在 Hugo 中使用 tailwind-v4-shadcn 技能模式。该技能适用于 Vite + React 项目，与 Hugo 的资源管道不兼容。

方面	Vite + React	Hugo
构建系统	JavaScript (Node.js)	Go (Hugo 二进制文件)
Tailwind 集成	@tailwindcss/vite 插件	Tailwind CLI + PostCSS
配置文件	vite.config.ts	hugo.yaml
内容扫描	content: [] glob 模式	hugo_stats.json
开发服务器	Vite（端口 5173）	Hugo（端口 1313）
深色模式	React ThemeProvider	CSS 类或 Alpine.js

快速开始（10 分钟）

1. 安装依赖项

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init

2. 配置 Hugo（hugo.yaml）

build:
  writeStats: true  # Generates hugo_stats.json for Tailwind

module:
  mounts:
    - source: assets
      target: assets
    - source: hugo_stats.json
      target: assets/watching/hugo_stats.json

3. 配置 Tailwind（tailwind.config.js）

module.exports = {
  content: [
    './hugo_stats.json',
    './layouts/**/*.html',
    './content/**/*.{html,md}',
  ],
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        primary: '#0066cc',
      },
    },
  },
  plugins: [],
}

4. 配置 PostCSS（postcss.config.js）

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

5. 创建 CSS 入口文件（assets/css/main.css）

@import "tailwindcss";

@layer base {
  body {
    @apply bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100;
  }
}

6. 在模板中处理 CSS（layouts/_default/baseof.html）

<head>
  {{ $style := resources.Get "css/main.css" | resources.PostCSS }}
  {{ if hugo.IsProduction }}
    {{ $style = $style | minify | fingerprint }}
  {{ end }}
  <link rel="stylesheet" href="{{ $style.RelPermalink }}">
</head>

7. 启动开发

hugo server

完整集成指南

完整的 Tailwind v4 + Hugo 设置指南，内容包括：

• 深色模式实现（仅 CSS 和 Alpine.js）
• Typography 插件设置
• Forms 插件设置
• 模板集成模式
• 常见问题及解决方案
• 生产构建优化

参见附带资源：

• 参考指南：references/tailwind-v4-integration.md（完整文档）
• 最小化模板：templates/hugo-tailwind-minimal/（起点）
• 博客模板：templates/hugo-tailwind-blog/（使用 Tailwind 构建的完整博客）

Tailwind 特有问题

使用 Tailwind 和 Hugo 时的常见问题（参考指南均提供了相应解决方案）：

问题	原因	解决方案
CSS 未处理	未配置 PostCSS	在模板中检查 resources.PostCSS
类未清除	未生成 hugo_stats.json	在 hugo.yaml 中启用 writeStats: true
深色模式失效	配置错误	在 tailwind.config.js 中使用 darkMode: 'class'
资源指纹生成失败	Hugo Pipes 用法不正确	使用 RelPermalink，而非 Permalink
CSS 中出现 Hugo 模板语法	CSS 中不能使用 {{ }}	在模板中应用类，而非在 CSS 中应用
版本不匹配	CLI 与 PostCSS 插件版本不同	将所有组件更新到相同版本

---

常见模式

模式 1：使用 PaperMod 主题的博客

# Scaffold
hugo new site my-blog --format yaml
cd my-blog
git init
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

# Configure (see hugo.yaml example above)

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

# Develop
hugo server

# Build
hugo --minify

适用场景：个人博客、公司博客、新闻网站

模式 2：使用 Hugo Book 的文档网站

# Scaffold
hugo new site docs --format yaml
cd docs
git init
git submodule add https://github.com/alex-shpak/hugo-book.git themes/hugo-book

# Configure for docs (nested navigation, search)
# See: bundled template `templates/hugo-docs/`

# Create docs
hugo new content docs/getting-started/installation.md

# Build
hugo --minify

适用场景：技术文档、知识库、API 文档

模式 3：落地页

# Scaffold
hugo new site landing --format yaml

# Use custom layouts (no theme)
# See: bundled template `templates/hugo-landing/`

# Single-page structure
hugo new content _index.md

# Build
hugo --minify

适用场景：营销网站、产品页面、作品集

模式 4：多语言网站

# hugo.yaml
defaultContentLanguage: "en"
languages:
  en:
    languageName: "English"
    weight: 1
  es:
    languageName: "Español"
    weight: 2

# Content structure:
# content/
# ├── posts/
# │   └── post-1.en.md
# │   └── post-1.es.md

适用场景：国际化网站、本地化内容

---

使用捆绑资源

脚本（scripts/）

init-hugo.sh - 自动化 Hugo 项目设置

./scripts/init-hugo.sh blog my-blog
# Creates Hugo site with specified template (blog/docs/landing/minimal)
# Arguments: [template-type] [project-name]

deploy-workers.sh - 手动部署 Cloudflare Workers

./scripts/deploy-workers.sh
# Runs: hugo --minify && wrangler deploy

check-versions.sh - 验证 Hugo 和工具版本

./scripts/check-versions.sh
# Checks: Hugo version, Extended edition, wrangler, Node.js

模板（templates/）

可直接复制的完整 Hugo 项目：

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

• 深色/浅色模式、搜索、标签、归档
• 预配置 Sveltia CMS
• 用于 Workers 的 wrangler.jsonc
• GitHub Actions 工作流

templates/hugo-docs/ - 文档网站

• 嵌套导航、搜索、面包屑
• Hugo Book 主题
• 用于编辑文档的 Sveltia CMS

templates/hugo-landing/ - 落地页

• 主视觉区、功能、用户评价、行动号召
• 自定义布局（无主题）
• 针对转化进行了优化

templates/minimal-starter/ - 基础项目

• 无主题，空白起步
• 添加主题的设置指南
• 最简配置

适用场景：复制整个模板目录，即可快速开始新项目。

参考资料（references/）

Claude 可在需要时加载的详细指南：

• references/sveltia-integration-guide.md - 完整的 Sveltia CMS 设置和 OAuth 配置
• references/workers-deployment-guide.md - Cloudflare Workers 部署、CI/CD、自定义域名
• references/common-errors.md - 全部 9 个错误的详细解决方案
• references/theme-customization-guide.md - 覆盖布局、自定义 CSS、局部模板
• references/hugo-vs-alternatives.md - 与 Next.js、Astro、Jekyll 的比较

Claude 应加载这些资料的情况：用户询问特定主题（CMS 设置、部署、错误、主题定制、替代方案）

资源文件（assets/）

• assets/screenshots/ - Hugo 博客、Sveltia CMS 和部署的视觉示例
• assets/diagrams/ - Hugo 目录结构、部署工作流图

---

高级主题

自定义短代码

创建可重复使用的内容组件：

<div class="youtube-embed">
  <iframe
    src="https://www.youtube.com/embed/{{ .Get 0 }}"
    allowfullscreen>
  </iframe>
</div>

在内容中的用法：

{{< youtube dQw4w9WgXcQ >}}

图像处理

Hugo 内置了图像处理功能：

{{ $image := resources.Get "images/photo.jpg" }}
{{ $resized := $image.Resize "800x" }}
<img src="{{ $resized.RelPermalink }}" alt="Photo">

分类法自定义

创建标签/类别以外的自定义分类法：

# hugo.yaml
taxonomies:
  tag: tags
  category: categories
  series: series  # Custom taxonomy

数据文件

使用 JSON/YAML/TOML 数据文件：

# data/team.yaml
- name: Alice
  role: Developer
- name: Bob
  role: Designer

在模板中访问：

{{ range .Site.Data.team }}
  <div>{{ .name }} - {{ .role }}</div>
{{ end }}

---

依赖项

必需：

• Hugo v0.149.0+（Extended 版本）- 静态网站生成器

可选（用于部署）：

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

可选（用于 CMS）：

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

---

官方文档

• Hugo：https://gohugo.io/documentation/
• PaperMod Theme：https://github.com/adityatelange/hugo-PaperMod/wiki
• Sveltia CMS：https://github.com/sveltia/sveltia-cms
• Cloudflare Workers：https://developers.cloudflare.com/workers/
• Hugo Themes：https://themes.gohugo.io/

---

软件包版本（已于 2025-11-04 验证）

Hugo：v0.152.2+extended（2025 年 10 月 24 日） PaperMod：最新版（通过 Git 子模块） Sveltia CMS：最新版（通过 CDN） Wrangler：v4.37.1+（可用版本为 v4.45.3）

---

生产环境示例

此技能基于实际测试：

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

---

故障排除

问题：“SCSS support not enabled”错误

解决方案：安装 Hugo Extended，而不是 Standard。使用 hugo version | grep extended 验证

问题：部署后网站空白

解决方案：

1. 检查 hugo.yaml 中是否设置了 theme
2. 确认主题存在于 themes/ 目录中
3. 运行 git submodule update --init --recursive

问题：资源（CSS/JS/图片）未加载

解决方案：

1. 检查 hugo.yaml 中的 baseURL 是否与部署 URL 匹配
2. 或使用 hugo -b https://your-site.com
3. 或使用特定环境的配置

问题：文章未显示在网站上

解决方案：

1. 检查 frontmatter 中的 draft: false
2. 检查日期是否未设为未来日期
3. 或使用 --buildDrafts 和 --buildFuture 标志进行构建

问题：在 CI/CD 中找不到主题

解决方案：在 GitHub Actions 的 checkout 操作中添加 submodules: recursive

问题：Sveltia CMS 未加载

解决方案：

1. 使用 hugo 重新构建网站
2. 检查 public/ 中是否存在 /admin 目录
3. 验证 config.yml 语法
4. 检查浏览器控制台中的错误

---

完整设置检查清单

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

• 已安装 Hugo Extended v0.149.0+（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/common-errors.md，了解全部 9 个已记录错误及其解决方案
2. 验证设置流程中的所有步骤
3. 查看官方文档：https://gohugo.io/documentation/
4. 确保已安装 Hugo Extended（最常见的问题）

---

此技能提供可用于生产环境且零错误的 Hugo 设置。全部 9 个常见问题均有记录并已预防。