hugo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hugo Static Site Generator

Hugo静态站点生成器

Status: Production Ready | Last Updated: 2025-11-21 Latest Version: hugo@0.152.2+extended | Build Speed: <100ms

状态：可用于生产环境 | 最后更新：2025-11-21 最新版本：hugo@0.152.2+extended | 构建速度：<100ms

Quick Start (5 Minutes)

快速开始（5分钟）

1. Install Hugo Extended

1. 安装Hugo Extended版本

CRITICAL: Always install Hugo Extended edition (not Standard) unless you're certain you don't need SCSS/Sass support. Most themes require Extended.

bash

undefined

关键注意事项：务必安装Hugo Extended版本（而非标准版），除非你确定不需要SCSS/Sass支持。大多数主题都依赖该版本。

bash

undefined

macOS

brew install hugo

Linux (Ubuntu/Debian)

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

验证是否为Extended版本

hugo version # Should show "+extended"


**Why this matters:**
- Hugo Extended includes SCSS/Sass processing
- Most popular themes (PaperMod, Academic, Docsy) require Extended
- Standard edition will fail with "SCSS support not enabled" errors
- Extended has no downsides (same speed, same features + more)

hugo version # 应显示 "+extended"


**重要性说明**：
- Hugo Extended版本包含SCSS/Sass处理功能
- 大多数热门主题（PaperMod、Academic、Docsy）均依赖该版本
- 标准版会出现“SCSS support not enabled”错误
- Extended版本无任何弊端（速度相同，功能更丰富）

2. Create New Hugo Site

2. 创建新的Hugo站点

bash

undefined

bash

undefined

Use YAML format (not TOML) for better CMS compatibility

使用YAML格式（而非TOML）以获得更好的CMS兼容性

hugo new site my-blog --format yaml

Initialize Git

初始化Git

cd my-blog git init

Add PaperMod theme (recommended for blogs)

添加PaperMod主题（博客推荐）

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


**CRITICAL:**
- Use `--format yaml` to create hugo.yaml (not hugo.toml)
- YAML is required for Sveltia CMS and recommended for TinaCMS
- TOML has known bugs in Sveltia CMS beta
- Git submodules require `--recursive` flag when cloning later

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
- TOML在Sveltia CMS测试版中存在已知bug
- 后续克隆项目时，Git子模块需要添加`--recursive`参数

3. Configure and Build

3. 配置与构建

yaml

undefined

yaml

undefined

hugo.yaml - Minimal working configuration

hugo.yaml - 最简可用配置

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


```bash

baseURL: "https://example.com/" title: "我的Hugo博客" theme: "PaperMod" languageCode: "en-us" enableRobotsTXT: true

params: ShowReadingTime: true ShowShareButtons: true defaultTheme: auto # 支持深色/浅色/自动模式


```bash

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

输出文件位于public/目录

---

---

Critical Rules

核心规则

Always Do

务必执行

✅ Install Hugo Extended (not Standard) - required for SCSS/Sass support in themes ✅ Use YAML configuration (

--format yaml

) - better CMS compatibility than TOML ✅ Add themes as Git submodules - easier updates and version control ✅ Set correct baseURL - prevents broken asset links on deployment ✅ Pin Hugo version in CI/CD - prevents version mismatch errors between local and deployment ✅ Add
public/
to .gitignore - build output should not be committed ✅ Use
draft: false
- drafts don't appear in production builds ✅ Clone with
--recursive
flag - ensures theme submodules are fetched ✅ Use relative paths for images -

/images/photo.jpg

not

../images/photo.jpg

✅ Test build before deploying - catch errors locally with

hugo --minify

✅ 安装Hugo Extended版本（而非标准版）- 主题的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

排查错误

Never Do

禁止操作

❌ Don't install Hugo Standard - most themes require Extended edition ❌ Don't use TOML config with Sveltia CMS - has known bugs, use YAML instead ❌ Don't commit
public/
directory - it's generated output, not source code ❌ Don't use different Hugo versions - local vs CI/CD version mismatch causes errors ❌ Don't forget
submodules: recursive
- themes won't load in CI/CD ❌ Don't hardcode production URLs - use

-b $CF_PAGES_URL

or environment configs ❌ Don't push
resources/_gen/
- generated assets, should be in .gitignore ❌ Don't use future dates carelessly - posts won't publish until date passes ❌ Don't skip
.hugo_build.lock
- add to .gitignore ❌ Don't mix YAML and TOML - stick to one format throughout project

❌ 不要安装Hugo标准版 - 大多数主题依赖Extended版本 ❌ 不要在Sveltia CMS中使用TOML配置 - 存在已知bug，请使用YAML ❌ 不要提交
public/
目录 - 这是生成的输出文件，而非源代码 ❌ 不要使用不同的Hugo版本 - 本地与CI/CD版本不匹配会引发错误 ❌ 不要忘记
submodules: recursive
- CI/CD环境中主题无法加载 ❌ 不要硬编码生产环境URL - 使用

-b $CF_PAGES_URL

或环境变量配置 ❌ 不要推送
resources/_gen/
- 生成的资源文件应加入.gitignore ❌ 不要随意使用未来日期 - 文章在日期到达前不会发布 ❌ 不要忽略
.hugo_build.lock
- 将其添加到.gitignore ❌ 不要混合使用YAML和TOML - 整个项目需坚持使用一种格式

Top 5 Errors Prevention

五大常见错误预防

This skill prevents 15 documented errors. Here are the top 5:

本技能可避免15种已记录的错误，以下是最常见的5种：

Error #1: Version Mismatch (Hugo vs Hugo Extended)

错误1：Hugo版本不匹配（标准版 vs Extended版）

Error:

Error: SCSS support not enabled

Prevention: Always install Hugo Extended edition. Verify with

hugo version | grep extended

See:

references/error-catalog.md

for full error list

错误信息：

Error: SCSS support not enabled

预防方案：始终安装Hugo Extended版本，通过

hugo version | grep extended

验证详情：查看

references/error-catalog.md

获取完整错误列表

Error #2: baseURL Configuration Errors

错误2：baseURL配置错误

Error: Broken CSS/JS/image links, 404s on all assets Prevention: Use environment-specific configs or build flag:

hugo -b $CF_PAGES_URL

See:

references/error-catalog.md

错误表现：CSS/JS/图片链接失效，所有资源返回404 预防方案：使用环境特定配置或构建参数：

hugo -b $CF_PAGES_URL

详情：查看

references/error-catalog.md

Error #3: Theme Not Found Errors

错误3：主题未找到

Error:

Error: module "PaperMod" not found

, blank site Prevention: Set

theme: "PaperMod"

in hugo.yaml and run

git submodule update --init --recursive

See:

references/error-catalog.md

错误信息：

Error: module "PaperMod" not found

，站点显示空白 预防方案：在hugo.yaml中设置

theme: "PaperMod"

，并执行

git submodule update --init --recursive

详情：查看

references/error-catalog.md

Error #4: Hugo Version Mismatch (Local vs Deployment)

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

Error: Features work locally but fail in CI/CD, or vice versa Prevention: Pin Hugo version everywhere (CI/CD, local docs, package.json if using npm) See:

references/error-catalog.md

错误表现：功能在本地正常，但在CI/CD中失败，反之亦然 预防方案：在所有环境中固定Hugo版本（CI/CD、本地文档、若使用npm则在package.json中配置）详情：查看

references/error-catalog.md

Error #5: Git Submodule Not Found in CI/CD

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

Error: Theme works locally but not in CI/CD, blank site on deployment Prevention: Add

submodules: recursive

to checkout action in GitHub Actions See:

references/error-catalog.md

#11

For complete error catalog (all 15 errors): See

references/error-catalog.md

错误表现：主题在本地正常，但在CI/CD中失效，部署后站点空白 预防方案：在GitHub Actions的checkout步骤中添加

submodules: recursive

详情：查看

references/error-catalog.md

#11

完整错误目录（共15种错误）：查看

references/error-catalog.md

Using Bundled Resources

配套资源使用

References (

references/

```
setup-guide.md
```
- Complete Hugo setup walkthrough (installation, themes, deployment)
```
error-catalog.md
```
- All 15 common Hugo errors with solutions and prevention
```
common-patterns.md
```
- Best practices and patterns (taxonomies, content organization, multilingual)
```
cms-integration.md
```
- Sveltia CMS integration guide with configuration
```
tailwind-integration.md
```
- Tailwind CSS integration with Hugo Pipes
```
advanced-topics.md
```
- Advanced Hugo features (modules, data files, internationalization)

参考文档（

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 (templates/)

模板（templates/）

Complete, production-ready Hugo projects ready to copy:

templates/hugo-blog/
- Blog with PaperMod theme
- Dark/light mode, search, tags, archives
- Sveltia CMS pre-configured
- wrangler.jsonc for Workers deployment
- GitHub Actions workflow included
- Use when: Building a personal blog, company blog, or news site
templates/hugo-docs/
- Documentation site with Hugo Book theme
- Nested navigation, search, breadcrumbs
- Sveltia CMS for docs editing
- Use when: Creating technical documentation, knowledge bases, API docs
templates/hugo-landing/
- Landing page with custom layouts
- Hero, features, testimonials, CTA sections
- No theme dependency (custom layouts)
- Optimized for conversions
- Use when: Building marketing sites, product pages, portfolios
templates/minimal-starter/
- Bare-bones starter
- No theme, clean slate
- Setup guide for adding themes
- Minimal configuration
- Use when: Starting from scratch with full control

Quick start with template:

bash

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

可直接复制使用的生产级Hugo项目模板：

templates/hugo-blog/
- 基于PaperMod主题的博客模板
- 深色/浅色模式、搜索、标签、归档
- 预配置Sveltia CMS
- 包含Workers部署的wrangler.jsonc
- 内置GitHub Actions工作流
- 适用场景：搭建个人博客、企业博客或新闻站点
templates/hugo-docs/
- 基于Hugo Book主题的文档站点模板
- 嵌套导航、搜索、面包屑
- 支持Sveltia CMS编辑文档
- 适用场景：创建技术文档、知识库、API文档
templates/hugo-landing/
- 自定义布局的着陆页模板
- 包含Hero、功能介绍、客户 testimonial、CTA板块
- 不依赖主题（自定义布局）
- 针对转化优化
- 适用场景：搭建营销站点、产品页面、作品集
templates/minimal-starter/
- 极简启动模板
- 无主题，从零开始
- 包含主题添加指南
- 极简配置
- 适用场景：需要完全自定义的项目

模板快速启动：

bash

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

References (references/)

参考文档（references/）

Detailed guides loaded when needed:

references/setup-guide.md
- Complete 7-step setup process
- Installation and verification
- Project scaffolding
- Theme installation
- Configuration options
- Content creation
- Build and development
- Cloudflare Workers deployment
- Load when: Setting up new Hugo project from scratch
references/cms-integration.md
- Headless CMS integration
- Sveltia CMS setup (recommended) - 5 minutes
- OAuth configuration for production
- TinaCMS setup (not recommended)
- Comparison and troubleshooting
- Load when: Adding content management to Hugo site
references/tailwind-integration.md
- Tailwind CSS v4 integration
- Hugo Pipes + PostCSS setup
- Dark mode implementation (CSS-only and Alpine.js)
- Typography and Forms plugins
- Production optimization
- Common issues and solutions
- Load when: Integrating Tailwind CSS with Hugo
references/common-patterns.md
- 7 common project patterns
- Blog with PaperMod
- Documentation with Hugo Book
- Landing pages
- Multilingual sites
- Portfolio sites
- E-commerce (static)
- Newsletter/blog
- Load when: Choosing architecture for specific use case
references/advanced-topics.md
- Advanced Hugo features
- Custom shortcodes
- Image processing
- Custom taxonomies
- Data files (JSON/YAML/CSV)
- Page bundles
- Template overrides
- Hugo Modules
- Load when: User needs advanced customization
references/error-catalog.md
- All 15 documented errors
- Complete error messages and solutions
- Prevention strategies
- Official sources cited
- Troubleshooting guide
- Load when: Debugging issues or preventing known errors

按需加载的详细指南：

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种已记录错误
- 完整错误信息与解决方案
- 预防策略
- 官方来源引用
- 故障排查指南
- 加载时机：调试问题或预防已知错误时

Common Use Cases

常见使用场景

Use Case 1: Personal Blog

场景1：个人博客

Template:

templates/hugo-blog/

Theme: PaperMod Time to deploy: 10 minutes Features: Search, tags, dark mode, RSS, Sveltia CMS

bash

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

See

references/common-patterns.md

→ Pattern 1

模板：

templates/hugo-blog/

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

bash

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

Use Case 2: Technical Documentation

场景2：技术文档

Template:

templates/hugo-docs/

Theme: Hugo Book Time to deploy: 10 minutes Features: Nested navigation, search, breadcrumbs, multi-language

bash

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

See

references/common-patterns.md

→ Pattern 2

模板：

templates/hugo-docs/

主题：Hugo Book 部署时间：10分钟功能：嵌套导航、搜索、面包屑、多语言

bash

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

Use Case 3: Landing Page

场景3：着陆页

Template:

templates/hugo-landing/

Theme: None (custom layouts) Time to deploy: 15 minutes Features: Hero, features, testimonials, CTA, contact form

bash

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

See

references/common-patterns.md

→ Pattern 3

模板：

templates/hugo-landing/

主题：无（自定义布局） 部署时间：15分钟功能：Hero、功能介绍、客户 testimonial、CTA、联系表单

bash

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

查看

references/common-patterns.md

→ 模式3

Use Case 4: Blog with Tailwind CSS v4

场景4：搭配Tailwind CSS v4的博客

Template: Start with

templates/minimal-starter/

Integration: Follow

references/tailwind-integration.md

Time to setup: 30 minutes Features: Custom design, utility-first CSS, dark mode

bash

cp -r templates/minimal-starter/ tailwind-blog/
cd tailwind-blog

模板：从

templates/minimal-starter/

开始 集成指南：遵循

references/tailwind-integration.md

搭建时间：30分钟功能：自定义设计、实用优先CSS、深色模式

bash

cp -r templates/minimal-starter/ tailwind-blog/
cd tailwind-blog

Follow references/tailwind-integration.md for setup

按照references/tailwind-integration.md完成配置


See `references/tailwind-integration.md` → Quick Start


查看`references/tailwind-integration.md` → 快速开始

Use Case 5: Multilingual Documentation

场景5：多语言文档

Template:

templates/hugo-docs/

Pattern: Multilingual Time to setup: 20 minutes Features: Language switcher, translated content, per-language menus

See

references/common-patterns.md

→ Pattern 4

模板：

templates/hugo-docs/

模式：多语言 搭建时间：20分钟功能：语言切换器、翻译内容、按语言显示菜单

查看

references/common-patterns.md

→ 模式4

Cloudflare Workers Deployment

Cloudflare Workers部署

Quick Deployment

快速部署

1. Create wrangler.jsonc:

jsonc

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

2. Deploy:

bash

hugo --minify
bunx wrangler deploy

For complete deployment guide: See

references/setup-guide.md

→ Step 7

1. 创建wrangler.jsonc：

jsonc

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

2. 部署：

bash

hugo --minify
bunx wrangler deploy

完整部署指南：查看

references/setup-guide.md

→ 步骤7

When to Load Detailed References

何时加载详细参考文档

Load
references/setup-guide.md
when:

User needs complete 7-step setup process
User asks about configuration options
User needs detailed installation instructions
User asks about directory structure
User needs GitHub Actions workflow

Load
references/cms-integration.md
when:

User wants to add CMS to Hugo site
User asks about Sveltia CMS setup
User asks about TinaCMS (warn it's not recommended)
User needs OAuth configuration
User asks about content management

Load
references/tailwind-integration.md
when:

User wants to integrate Tailwind CSS v4
User asks about PostCSS setup
User needs dark mode implementation
User asks about Tailwind plugins
User has CSS processing errors

Load
references/common-patterns.md
when:

User asks "how do I build a [blog/docs/landing page]?"
User needs architecture guidance
User asks about multilingual sites
User asks about portfolio sites
User needs project structure examples

Load
references/advanced-topics.md
when:

User asks about shortcodes
User needs image processing
User wants custom taxonomies
User asks about data files
User needs template customization

Load
references/error-catalog.md
when:

User encounters an error
User asks about troubleshooting
User wants to prevent known issues
User asks "what errors should I watch out for?"
User has deployment issues

加载
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
的时机：

用户遇到错误
用户询问故障排查
用户想预防已知问题
用户询问“需要注意哪些错误？”
用户遇到部署问题

Dependencies

依赖项

Required:

Hugo v0.149.0+ (Extended edition) - Static site generator

Optional (for deployment):

wrangler v4.0.0+ - Cloudflare Workers deployment
Git v2.0+ - Version control and theme submodules

Optional (for CMS):

Sveltia CMS (latest) - Content management (CDN-based, no installation)

必需依赖：

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

可选依赖（部署用）：

wrangler v4.0.0+ - Cloudflare Workers部署工具
Git v2.0+ - 版本控制与主题子模块管理

可选依赖（CMS用）：

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

Official Documentation

官方文档

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

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/

Package Versions (Verified 2025-11-04)

已验证的包版本（2025-11-04）

Hugo: v0.152.2+extended (October 24, 2025) PaperMod: Latest (via Git submodule) Sveltia CMS: Latest (via CDN) Wrangler: v4.37.1+ (v4.45.3 available)

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

Production Example

生产环境示例

This skill is based on live testing:

Test Site: https://hugo-blog-test.webfonts.workers.dev
Build Time: 24ms (20 pages)
Deployment Time: ~21 seconds
Errors: 0 (all 15 known issues prevented)
Validation: ✅ Hugo + PaperMod + Sveltia + Workers deployed successfully

本技能基于实际测试：

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

Complete Setup Checklist

完整搭建检查清单

Use this checklist to verify your setup:

Hugo Extended v0.149.0+ installed (
```
hugo version
```
shows "+extended")
Project created with
```
--format yaml
```
(hugo.yaml exists)
Theme installed and configured (via Git submodule or Hugo Module)
```
baseURL
```
configured correctly in hugo.yaml
```
.gitignore
```
includes
```
public/
```
and
```
resources/_gen/
```
Sample content created and renders correctly
Dev server runs without errors (
```
hugo server
```
)
Production build succeeds (
```
hugo --minify
```
)
wrangler.jsonc configured for Workers (if deploying)
Sveltia CMS configured (if using CMS)
GitHub Actions workflow configured (if using CI/CD)
Deployed successfully (if deploying to Workers)

Questions? Issues?

Check
```
references/error-catalog.md
```
for all 15 documented errors and solutions
Verify all steps in the setup process
Use appropriate template from
```
templates/
```
directory
Load relevant reference guide for detailed information
Check official docs: https://gohugo.io/documentation/

This skill provides production-ready Hugo setup with zero errors. All 15 common issues are documented and prevented.

使用此清单验证你的搭建是否完成：

已安装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
```
无错误）
已配置wrangler.jsonc用于Workers部署（若部署）
已配置Sveltia CMS（若使用CMS）
已配置GitHub Actions工作流（若使用CI/CD）
已成功部署（若部署到Workers）

有疑问？遇到问题？

查看
```
references/error-catalog.md
```
获取所有15种已记录错误的解决方案
验证搭建流程中的所有步骤
使用
```
templates/
```
目录中的合适模板
加载相关参考文档获取详细信息
查看官方文档：https://gohugo.io/documentation/

本技能提供零错误的生产级Hugo搭建方案，所有15种常见问题均已记录并预防。