# Hugo 静态站点生成器 **状态**：生产就绪 **最后更新**：2025-11-04 **依赖项**：无（Hugo 是一个独立的二进制文件） **最新版本**：hugo@0.152.2+extended、PaperMod@latest、Sveltia CMS@latest ** ** ## 快速入门（5 分钟） ### 1\.安装 Hugo 扩展 **重要** ：除非您确定不需要 SCSS/Sass 支持，否则始终安装 Hugo **扩展**版本（非标准版）。大多数主题需要扩展。 # macOS 酿造安装雨果 # Linux (Ubuntu/Debian) wget https://github.com/gohugoio/hugo/releases/download/v0.152.2/hugo_extended_0.152.2_linux-amd64.deb sudo dpkg -ihugo_extended_0.152.2_linux-amd64.deb # 验证扩展版本 Hugo 版本 # 应显示“+extend” **为什么这很重要：** * Hugo Extended 包括 SCSS/Sass 处理 * 最流行的主题（PaperMod、Academic、Docsy）需要扩展 * 标准版将失败并出现“SCSS 支持未启用”错误 * 扩展没有缺点（相同的速度，相同的功能+更多） ### 2\.创建新的 Hugo 网站 # 使用 YAML 格式（而不是 TOML）以获得更好的 CMS 兼容性雨果新网站我的博客 --format yaml # 初始化Git cd 我的博客 git初始化 # 添加 PaperMod 主题（推荐用于博客） git 子模块添加 --depth=1 https://github.com/adityatelange/hugo-PaperMod.git theme/PaperMod **关键：** * 使用`--format yaml`创建hugo.yaml（不是hugo.toml） * Sveltia CMS 需要 YAML，建议 TinaCMS 使用 YAML * TOML 在 Sveltia CMS beta 中存在已知错误 * 稍后克隆时，Git 子模块需要 `--recursive` 标志 ### 3\.配置和构建 #hugo.yaml - 最小工作配置基本网址：“https://example.com/” 标题：“我的雨果博客” 主题：“PaperMod” 语言代码：“en-us” 启用RobotsTXT：真参数：显示阅读时间： true 显示共享按钮：true defaultTheme: auto # 支持深色/浅色/自动 # 创建第一篇文章雨果新内容 posts/first-post.md # 运行开发服务器（实时重新加载）雨果服务器 # 为生产而构建雨果——缩小 # 输出位于 public/ 目录中 ** ** ## 7 步设置过程 ### 第 1 步：安装和验证 **使用以下方法之一安装 Hugo Extended**： **方法 1：自制程序 (macOS/Linux)** ✅ 推荐酿造安装雨果 **方法 2：二进制下载 (Linux)** # 查看最新版本：https://github.com/gohugoio/hugo/releases 版本=“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 Wrapper**（不推荐，可能会落后） npm install -g 雨果-bin **验证：** 雨果版 # 应该输出：hugo v0.152.2+extended # ^^^^^^^^^ 必须显示“+extend” **要点：** * SCSS/Sass 需要扩展版 * 版本应为 v0.149.0+ 以获得最佳兼容性 * NPM 包装器可能落后于官方版本 * CI/CD 中的引脚版本（参见步骤 7） ### 第 2 步：项目脚手架 **使用 YAML 配置创建新站点：** 雨果新网站我的网站-格式yaml cd 我的网站 **创建的目录结构：** 我的网站/ ├── humo.yaml # 配置（YAML 格式） ├── archetypes/ # 内容模板 │ └── 默认.md ├── content/ # 你所有的内容都放在这里 ├── data/ # 数据文件(JSON/YAML/TOML) ├── 布局/ # 模板覆盖 ├── static/ # 静态资源（图片、CSS、JS） ├── theme/ # 主题目录 └── public/ # 构建输出（生成，git忽略） **关键：** * 使用 `--format yaml` 实现 CMS 兼容性 * 切勿将 `public/` 目录提交到 Git * 立即创建`.gitignore`（参见步骤3） ### 步骤 3：主题安装 **推荐方法：Git 子模块** ✅ # 流行主题： # - PaperMod（博客）：https://github.com/adityatelange/hugo-PaperMod # - 书籍（文档）：https://github.com/alex-shpak/hugo-book # - 学术（研究）：https://github.com/HugoBlox/theme-academic-cv # - Ananke（一般）：https://github.com/theNewDynamic/gohugo-theme-ananke git 子模块添加 --depth=1 https://github.com/adityatelange/hugo-PaperMod.git theme/PaperMod **替代方案：Hugo 模块**（高级） Hugo mod init github.com/username/my-site # 在hugo.yaml中： # 模块： # 进口： # - 路径：github.com/adityatelange/hugo-PaperMod **将主题添加到hugo.yaml：** 主题：“PaperMod” **使用子模块克隆项目时：** git clone --recursive https://github.com/username/my-site.git # 或者如果已经克隆： git 子模块更新 --init --recursive **要点：** * 建议使用 Git 子模块而不是手动下载 * `--depth=1` 节省空间（没有主题历史记录） * 克隆后始终运行 `git submodule update --init --recursive` * Hugo 模块更高级，但不需要 Git 子模块 ### 步骤 4：配置 **hugo.yaml - 完整示例（PaperMod 博客）：** 基本网址：“https://example.com/” 标题：“我的雨果博客” 主题：“PaperMod” 语言代码：“en-us” 默认内容语言：“en” 启用RobotsTXT：真构建草稿：假构建未来：假构建过期：假启用表情符号：true 缩小：禁用XML：true 缩小输出：true 参数：环境：生产标题：“我的雨果博客” 描述：“用 Hugo 和 PaperMod 构建的博客” 作者：《你的名字》显示阅读时间： true 显示共享按钮：true ShowPostNavLinks：true 显示面包屑：true 显示代码复制按钮：true defaultTheme: auto # 深色、浅色、自动社交图标： - 名称：推特网址：“https://twitter.com/用户名” - 名称：github 网址：“https://github.com/用户名” 菜单：主要： - 标识符：帖子名称：帖子网址：/帖子/ 重量：10 - 标识符：关于名称：关于网址：/关于/ 重量：20 输出：家： - HTML - RSS - JSON # 搜索所需 **配置格式：** * **YAML** (推荐): `hugo.yaml` \- 更好的 CMS 兼容性 * **TOML** （旧版）：`hugo.toml` \- 默认但 Sveltia CMS 存在问题 * **JSON** : `hugo.json` \- 很少使用 **特定于环境的配置：** 配置/ ├── _默认/ │ └── humo.yaml ├── 生产/ │ └── humo.yaml # 生产环境的覆盖 └── 开发/ └── humo.yaml # 本地开发的覆盖 ### 第 5 步：内容创建 **使用 Hugo CLI 创建内容：** # 博客文章雨果新内容帖子/my-first-post.md # 页雨果新内容 about.md # 嵌套文档 Hugo 新内容 docs/getting-started/installation.md **Frontmatter 格式（推荐 YAML）：** --- 标题：“我的第一篇文章” 日期: 2025-11-04T10:00:00+11:00 草稿：假标签：[“雨果”、“博客”] 类别：[“一般”] 描述：“SEO 的简要描述” 封面：图片：“/images/cover.jpg” alt：“封面图片” --- # 帖子内容从这里开始这是我的第一篇 Hugo 博客文章！ **TOML Frontmatter（仅供参考）：** +++ title =“我的第一篇文章” 日期 = 2025-11-04T10:00:00+11:00 草稿=假标签= [“雨果”，“博客”] +++ **要点：** * 对 YAML frontmatter 使用 `---` 分隔符 * TOML frontmatter 使用 `+++` 分隔符 * 帖子出现在生产中需要“草稿：假” * 未来的“日期” = 帖子不会发布（除非使用“--buildFuture”标志） * 内容位于 frontmatter 结束分隔符之后 ### 第 6 步：构建和开发 **开发服务器（实时重新加载）：** # 启动服务器雨果服务器 # 草稿可见雨果服务器--buildDrafts # 包含未来日期的帖子雨果服务器--buildFuture # 绑定到特定端口雨果服务器--端口1314 # 访问地址：http://localhost:1313 **生产版本：** # 基本构建雨果 # 缩小（推荐）雨果——缩小 # 具有特定的baseURL（用于部署） Hugo --minify --baseURL https://example.com # 或者使用环境变量雨果 --minify -b $CF_PAGES_URL **构建输出：** * 所有生成的文件都进入 `public/` 目录 * 典型构建时间：小型网站<100ms，1000+页面<5s * Hugo 是**最快**的静态站点生成器 **要点：** * 开发服务器具有实时重新加载（HMR） * 生产版本应该使用 `--minify` * 永远不要提交 `public/` 目录 * 构建时间非常快（Hugo 是用 Go 编写的） ### 步骤 7：Cloudflare Workers 部署 **创建wrangler.jsonc：** { “名称”：“我的雨果网站”， “兼容性日期”：“2025-01-29”， “资产”：{ "目录": "./public", "html_handling": "自动尾随斜杠", "not_found_handling": "404 页" } } **手动部署：** # 构建站点雨果——缩小 # 部署到工人 npx 牧马人部署 **GitHub 操作（自动）：** 创建`.github/workflows/deploy.yml`：名称：部署到 Cloudflare Workers 于：推：分支：[主要] 职位：部署：运行：ubuntu-latest 步骤： - 名称：结账使用：actions/checkout@v4 与： submodules: recursive # 对于主题子模块很重要！ - 名称：设置雨果用途：peaceiris/actions-hugo@v2 与：雨果版本：'0.152.2' 扩展：真实 - 名称：构建运行：hugo --minify - 名称：部署到 Cloudflare Workers 使用：cloudflare/wrangler-action@v3 与： 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**（非标准） - 主题中支持 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** \- 大多数主题需要扩展版 ❌ **不要在 Sveltia CMS 中使用 TOML 配置** \- 存在已知错误，请使用 YAML ❌ **不要提交`public/` 目录** \- 它是生成的输出，而不是源代码 ❌ **不要使用不同的 Hugo 版本** \- 本地与 CI/CD 版本不匹配会导致错误 ❌ **不要忘记`子模块：递归`** \- 主题不会在 CI/CD 中加载 ❌ **不要硬编码生产 URL** \- 使用 `-b $CF_PAGES_URL` 或环境配置 ❌ **不要推送`resources/_gen/`** \- 生成的资产，应该在 .gitignore 中 ❌ **不要不小心使用未来的日期** \- 帖子在日期过去之前不会发布 ❌ **不要跳过 `.hugo_build.lock`** \- 添加到 .gitignore ❌ **不要混合 YAML 和 TOML** \- 在整个项目中坚持一种格式 ** ** ## 已知问题预防此技能可防止 **9** 记录的问题： ### 问题 #1：版本不匹配（Hugo 与 Hugo Extended） **错误**：`错误：未启用 SCSS 支持` **来源**： **为什么会发生**：主题需要 SCSS/Sass 处理，但 Hugo Standard 不包含它 **预防**：始终安装 Hugo Extended 版本。使用 `hugo 版本 | 进行验证grep 扩展` ### 问题 #2：baseURL 配置错误 **错误**：CSS/JS/图像链接损坏，所有资产均出现 404 错误 **来源**：Hugo 文档、Cloudflare Pages 指南 **发生原因**：配置中的 `baseURL` 与部署 URL 不匹配 **预防**： * 使用特定于环境的配置（`config/product/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 humo-setup、Cloudflare Pages 文档 **为什么会发生**：不同的 Hugo 版本有不同的功能/错误 **预防**： * 在 `hugo.yaml` 元数据或 README 中固定 Hugo 版本 * 在 Cloudflare 页面中设置 `HUGO_VERSION` * 在 GitHub Actions 中使用 `hugo-version: '0.152.2'` ### 问题 #5：内容 Frontmatter 格式错误 **错误**：内容文件不渲染，构建因解析错误而失败 **来源**：Hugo 内容管理文档 **为什么会发生**：错误的分隔符（`---` vs `+++`），无效的 YAML/TOML 语法 **预防**： * YAML：使用 `---` 分隔符 * TOML：使用 `+++` 分隔符 * 使用 Sveltia CMS 或 YAML linter 验证 frontmatter ### 问题 #6：未找到主题错误 **错误**：`错误：找不到模块“PaperMod”`，空白站点 **来源**：Hugo 主题文档 **为什么会发生**：主题未安装，或“主题”未在配置中设置，或 Git 子模块未初始化 **预防**： * 在hugo.yaml中设置`主题：“PaperMod”` * 使用 `git submodule add` 进行主题安装 * 克隆后始终“git submodule update --init --recursive” ### 问题 #7：日期时间扭曲问题 **错误**：部署站点上缺少内容，但在本地可见 **来源**：Hugo 日期处理文档 **为什么会发生**：本地发布的未来日期的帖子（使用 `--buildFuture`）但不在生产中 **预防**： * 在 frontmatter 中使用当前或过去的日期 * 或者将 `--buildFuture` 标志添加到生产构建中 * 检查 frontmatter 中的“日期”字段 ### 问题 #8：公用文件夹冲突 **错误**：网站内容陈旧，Git 在 `public/` 中发生冲突 **来源**：Hugo 项目结构最佳实践 **为什么会发生**：在应该仅构建输出时提交 `public/` 目录 **预防**： * 添加 `public/` 到 `.gitignore` * 在每次部署时重建 * 永远不要提交生成的文件 ### 问题#9：模块缓存问题 **错误**：`无法提取短代码`，损坏的模块缓存 **来源**：Hugo 模块文档，GitHub 问题 **为什么会发生**：损坏的 Hugo 模块缓存（当使用模块而不是子模块时） **预防**： * 运行 `hugo mod clean` 清除缓存 * 定期运行 `hugo mod tidy` * 或者使用Git子模块代替模块（更可靠） ** ** ## 配置文件参考 ### humo.yaml（完整生产示例）基本网址：“https://example.com/” 标题：“我的雨果博客” 主题：“PaperMod” 语言代码：“en-us” 默认内容语言：“en” 启用RobotsTXT：真构建草稿：假构建未来：假构建过期：假启用表情符号：true pygmentsUseClasses：true 摘要长度：30 缩小：禁用XML：true 缩小输出：true 参数：环境：生产标题：“我的雨果博客” 描述：“用 Hugo 和 PaperMod 构建的博客” 关键词：[博客、雨果、科技] 作者：《你的名字》图片：[“/images/og-image.jpg”] 日期格式：“2006 年 1 月 2 日” defaultTheme: auto # 深色、浅色、自动禁用主题切换： false 显示阅读时间： true 显示共享按钮：true ShowPostNavLinks：true 显示面包屑：true 显示代码复制按钮：true 显示字数：true ShowRssButtonInSectionTermList：true 使用HugoToc：true 禁用Special1stPost：假禁用ScrollToTop：假评论：假的隐藏元：假 hide总结： false 显示目录：正确托科彭：假资产：禁用HLJS：true 禁用指纹识别： false 标签：文本：“我的雨果博客” 图标：/favicon.ico 图标高度：35 主页信息参数：标题：《你好👋》内容：欢迎来到我的博客。社交图标： - 名称：推特网址：“https://twitter.com/” - 名称：github 网址：“https://github.com/” - 名称：linkedin 网址：“https://linkedin.com/” - 名称：RSS 网址：“/index.xml” 封面：隐藏：假隐藏在列表中：假隐藏单：假编辑帖子：网址：“https://github.com/username/repo/tree/main/content” 文本：“建议更改” 附加文件路径：true 保险丝选项：是否区分大小写： false 应该排序：true 位置: 0 距离：1000 阈值：0.4 最小匹配字符长度：0 键：[“标题”、“永久链接”、“摘要”、“内容”] 菜单：主要： - 标识符：搜索名称：搜索网址：/搜索/ 重量：10 - 标识符：帖子名称：帖子网址：/帖子/ 重量：20 - 标识符：档案名称：档案馆网址：/档案/ 重量：30 - 标识符：标签名称：标签网址：/标签/ 重量：40 - 标识符：关于名称：关于网址：/关于/ 重量：50 输出：家： - HTML - RSS - JSON # 搜索功能所需 **为什么要进行这些设置：** * `buildDrafts: false` \- 防止生产中的草稿 * `enableRobotsTXT: true` \- SEO 最佳实践 * `minifyOutput: true` \- 较小的文件大小 * `defaultTheme: auto` \- 尊重用户的系统偏好 * `JSON` 输出 - 启用客户端搜索 * 社交图标 - 提高可发现性 ### wrangler.jsonc（Cloudflare Workers） { “名称”：“我的雨果网站”， “兼容性日期”：“2025-01-29”， “资产”：{ "目录": "./public", "html_handling": "自动尾随斜杠", "not_found_handling": "404 页" } } **为什么要进行这些设置：** * `directory: "./public"` \- Hugo 的构建输出 * `html_handling: "auto-trailing-slash"` \- 匹配 Hugo 的 URL 结构 * `not_found_handling: "404-page"` \- 服务 Hugo 的自定义 404.html ### .gitignore（必需） # 雨果 /公共/ /资源/_gen/ .hugo_build.lock # 操作系统 .DS_Store 拇指数据库 # 编辑器 .vscode/ .想法/ *.swp *.swo # 依赖项（如果使用 npm 作为工具）节点模块/ 包锁.json # 日志 *.log ** ** ## Sveltia CMS 集成（推荐） ### 为什么选择 Sveltia CMS for Hugo？ ✅ **Hugo 是 Sveltia 的主要用例** \- 专为 Hugo 设计 ✅ **设置简单** \- 2 个静态文件，无需构建步骤 ✅ **无 npm 依赖项** \- 单个 CDN 脚本 ✅ **本地后端** \- 无需 Git 即可在本地测试 CMS ✅ **YAML frontmatter** \- 完全兼容 ✅ **无安全漏洞** \- 轻量级，可维护 ✅ **主动开发** \- 专注于静态站点生成器 ### 设置（5 分钟） **1\.创建管理界面** \- `static/admin/index.html`: <头> <元字符集=“utf-8”/> <标题>内容管理器 <正文> **2\.创建 CMS 配置** \- `static/admin/config.yml`: 后端：名称：git网关分支：主干 local_backend: true # 启用本地测试 media_folder：“静态/图像/上传” public_folder：“/图像/上传” 收藏： - 名称：“博客” 标签：“博客文章” 文件夹：“内容/帖子” 创建：真实蛞蝓：“{{slug}}” 字段： - {标签：“标题”，名称：“标题”，小部件：“字符串”} - {标签：“描述”，名称：“描述”，小部件：“字符串”，必需：false} - {标签：“日期”，名称：“日期”，小部件：“日期时间”} - {标签：“草稿”，名称：“草稿”，小部件：“布尔值”，默认值：false} - {标签：“标签”，名称：“标签”，小部件：“列表”，必需：false} - {标签：“类别”，名称：“类别”，小部件：“列表”，必需：false} - {标签：“封面图片”，名称：“封面”，小部件：“对象”，必需：false，字段：[ {标签：“图像”，名称：“图像”，小部件：“图像”，必需：false}， {标签：“替代文本”，名称：“替代”，小部件：“字符串”，必需：false} ]} - {标签：“正文”，名称：“正文”，小部件：“markdown”} - 名称：“页面” 标签：“页面” 文件夹：“内容” 创建：真实蛞蝓：“{{slug}}” 过滤器：{字段：“类型”，值：“页面”} 字段： - {标签：“标题”，名称：“标题”，小部件：“字符串”} - {标签：“日期”，名称：“日期”，小部件：“日期时间”} - {标签：“类型”，名称：“类型”，小部件：“隐藏”，默认值：“页面”} - {标签：“草稿”，名称：“草稿”，小部件：“布尔值”，默认值：false} - {标签：“正文”，名称：“正文”，小部件：“markdown”} **3\.重建站点**：雨果 # 管理界面现在位于：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 月 4 日，4 个高漏洞，3 个严重漏洞） ❌ **React/Next.js集中** \- Hugo 是次要用例 ❌ **仅限 YAML** \- 与 Sveltia 相同的限制，没有好处 ### 如果您必须使用 TinaCMS 仅在以下情况下考虑 TinaCMS： * 已经在使用蒂娜云 * 拥有 React 专业知识 * 需要蒂娜特定的功能请参阅捆绑参考：“references/tinacms-integration-guide.md”（警告：不推荐） ** ** ## Tailwind CSS v4 集成 Hugo 通过 Hugo Pipes 和 Tailwind CLI 支持 Tailwind CSS v4。这种方式与基于 Vite 的 React 项目有着根本的不同。 ### 何时使用 Tailwind 与主题 **在以下情况下使用 Tailwind 和 Hugo：** * 不依赖主题构建自定义设计 * 需要实用优先的 CSS 工作流程 * 想要完整的造型控制 * 相比 SCSS/Sass 更喜欢 Tailwind **在以下情况下使用主题（PaperMod、Book 等）：** * 想要经过验证、可投入生产的设计 * 需要快速设置，无需自定义 CSS * 对主题定制选项感到满意 * 不需要像素完美的定制设计 ### 与 Vite + React 的主要区别 **重要：** 不要尝试对 Hugo 使用 `tailwind-v4-shadcn` 技能模式。该技能适用于 Vite + React 项目，与 Hugo 的资产管道不兼容。方面|投票 + 反应 |雨果 ---|---|--- **构建系统** | JavaScript (Node.js) | Go（Hugo 二进制） **顺风整合** | `@tailwindcss/vite` 插件 | Tailwind CLI + PostCSS **配置文件** | `vite.config.ts` | `hugo.yaml` **内容扫描** | `内容：[]` 全局 | `hugo_stats.json` **开发服务器** | Vite（端口5173）|雨果（端口 1313） **深色模式** |反应主题提供者 | CSS 类或 Alpine.js ### 快速入门（10 分钟） 1. **安装依赖项** npm install -D tailwindcss postcss autoprefixer npx tailwindcss 初始化 2. **配置Hugo** (`hugo.yaml`) 构建： writeStats: true # 为 Tailwind 生成hugo_stats.json 模块：坐骑： - 来源：资产目标：资产 - 来源：hugo_stats.json 目标：assets/watching/hugo_stats.json 3. **配置 Tailwind** (`tailwind.config.js`) 模块. 导出 = { 内容：[ './hugo_stats.json', './layouts/**/*.html', './content/**/*.{html,md}', ], 黑暗模式：'类'，主题：{ 扩展：{ 颜色：{ 主要：'#0066cc'， }, }, }, 插件：[]， } 4. **配置PostCSS** (`postcss.config.js`) 模块. 导出 = { 插件：{ tailwindcss: {}, 自动前缀：{}， }, } 5. **创建 CSS 入口文件** (`assets/css/main.css`) @导入“tailwindcss”； @层基础{ 身体{ @apply bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100; } } 6. **处理模板中的 CSS** (`layouts/_default/baseof.html`) <头> {{ $style := resources.Get "css/main.css" |资源.PostCSS }} {{如果hugo.IsProduction}} {{ $样式 = $样式 |缩小|指纹 }} {{结束}} 7. **开始开发** 雨果服务器 ### 完整集成指南完整的 Tailwind v4 + Hugo 设置包括： * 深色模式实现（仅 CSS 和 Alpine.js） * 版式插件设置 * 表单插件设置 * 模板集成模式 * 常见问题及解决方案 * 生产构建优化 **查看捆绑资源：** * **参考指南**：`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 为主题的博客 # 脚手架雨果新网站我的博客 --format yaml cd 我的博客 git初始化 git 子模块添加 --depth=1 https://github.com/adityatelange/hugo-PaperMod.git theme/PaperMod # 配置（参见上面的hugo.yaml示例） # 创建帖子雨果新内容 posts/first-post.md # 开发雨果服务器 # 构建雨果——缩小 **何时使用**：个人博客、公司博客、新闻网站 ### 模式 2：Hugo Book 的文档站点 # 脚手架 Hugo 新站点文档 --format yaml 光盘文档 git初始化 git 子模块添加 https://github.com/alex-shpak/hugo-book.git theme/hugo-book # 配置文档（嵌套导航、搜索） # 请参阅：捆绑模板 `templates/hugo-docs/` # 创建文档 Hugo 新内容 docs/getting-started/installation.md # 构建雨果——缩小 **何时使用**：技术文档、知识库、API 文档 ### 模式 3：登陆页面 # 脚手架 Hugo新站登陆--format yaml # 使用自定义布局（无主题） # 请参阅：捆绑模板 `templates/hugo-landing/` # 单页面结构雨果新内容_index.md # 构建雨果——缩小 **何时使用**：营销网站、产品页面、产品组合 ### 模式 4：多语言网站 #hugo.yaml 默认内容语言：“en” 语言： zh: 语言名称：“英语” 重量：1 es: 语言名称：“Español” 重量：2 # 内容结构： #内容/ # ├── 帖子/ # │ └── post-1.en.md # │ └── post-1.es.md **何时使用**：国际网站、本地化内容 ** ** ## 使用捆绑资源 ### 脚本（脚本/） **`init-hugo.sh`** \- 自动 Hugo 项目设置 ./scripts/init-hugo.sh 博客我的博客 # 使用指定模板创建 Hugo 站点 (blog/docs/landing/minimal) # 参数：[模板类型] [项目名称] **`deploy-workers.sh`** \- 手动 Cloudflare Workers 部署 ./scripts/deploy-workers.sh # 运行：hugo --minify && wrangler deploy **`check-versions.sh`** \- 验证 Hugo 和工具版本 ./scripts/check-versions.sh # 检查：Hugo 版本、扩展版本、wrangler、Node.js ### 模板（模板/）已完成、可运行的 Hugo 项目可供复制： **`templates/hugo-blog/`** \- 以 PaperMod 为主题的博客 * 暗/亮模式、搜索、标签、档案 * Sveltia CMS 预配置 * 用于 Workers 的 wrangler.jsonc * GitHub Actions 工作流程 **`templates/hugo-docs/`** \- 文档站点 * 嵌套导航、搜索、面包屑 * 雨果书主题 * Sveltia CMS 用于文档编辑 **`templates/hugo-landing/`** \- 登陆页面 * 英雄、特色、感言、CTA * 自定义布局（无主题） * 针对转化进行优化 **`templates/minimal-starter/`** \- 基本项目 *没有主题，干净的石板 * 添加主题设置指南 * 最低配置 **何时使用模板** ：复制整个模板目录以立即启动新项目。 ### 参考文献（参考文献/）克劳德可以在需要时加载详细指南： * `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/screenshots/` \- Hugo 博客、Sveltia CMS、部署的可视化示例 * `assets/diagrams/` \ - Hugo目录结构，部署工作流程图 ** ** ## 高级主题 ### 自定义短代码创建可重用的内容组件：

内容中的用法： {{< youtube dQw4w9WgXcQ >}} ### 图像处理 Hugo 具有内置图像处理功能： {{ $image := resources.Get "images/photo.jpg" }} {{ $resized := $image.Resize "800x" }}

### 分类定制创建标签/类别之外的自定义分类法： #hugo.yaml 分类法：标签：标签类别：类别系列：系列#自定义分类法 ### 数据文件使用 JSON/YAML/TOML 数据文件： # 数据/team.yaml - 姓名：爱丽丝角色：开发人员 - 姓名：鲍勃角色：设计师在模板中访问： {{ 范围.Site.Data.team }}

{{ .name }} - {{ .role }}

{{结束}} ** ** ## 依赖关系 **必填**： * Hugo v0.149.0+ (扩展版) - 静态站点生成器 **可选**（用于部署）： * wrangler v4.0.0+ - Cloudflare Workers 部署 * Git v2.0+ - 版本控制和主题子模块 **可选**（对于 CMS）： * Sveltia CMS（最新）- 内容管理（基于 CDN，无需安装） ** ** ## 官方文档 * **雨果**： * **PaperMod 主题** : * **Sveltia CMS**： * **Cloudflare Workers** ： * **Hugo 主题** : ** ** ## 软件包版本（2025-11-04 验证） **Hugo**：v0.152.2+扩展（2025 年 10 月 24 日） **PaperMod**：最新（通过 Git 子模块） **Sveltia CMS**：最新（通过 CDN） **Wrangler**：v4.37.1+（v4.45.3 可用） ** ** ## 制作示例该技能基于实时测试： * **测试站点**： * **构建时间**：24 毫秒（20 页） * **部署时间**：~21 秒 * **错误**：0（已阻止所有 9 个已知问题） * **验证**：✅ Hugo + PaperMod + Sveltia + Workers 部署成功 ** ** ## 故障排除 ### 问题：“SCSS 支持未启用”错误 **解决方案**：安装 Hugo Extended，而不是 Standard。使用 `hugo 版本 | 进行验证grep 扩展` ### 问题：部署后网站空白 **解决方案**： 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 中找不到主题 **解决方案**：将 `submodules: recursive` 添加到 GitHub Actions 中的签出操作 ### 问题：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 模块） * 在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.查看官方文档： 4. 确保已安装 Hugo Extended（最常见问题） ** ** **此技能提供生产就绪的 Hugo 设置，且零错误。所有 9 个常见问题均已记录并得到预防。**

雨果

包含技能