Hugo
概述
EdgeOne Pages 内置了对 Hugo 静态站点生成框架的完整支持。当你将 Hugo 项目部署到 Pages 时，系统会自动检测项目类型、管理 Hugo 版本、执行构建并缓存构建产物，实现零配置的 Hugo 站点持续集成与部署。
核心特性
自动识别 Hugo 项目，无需额外声明。
内置 Hugo Extended 版本，支持 SCSS/SASS 编译。
灵活的版本管理，支持指定任意 Hugo 版本。
自动缓存构建产物，加速重复构建。
快速开始
项目要求
确保你的 Hugo 项目根目录包含以下任意一个配置文件或目录：
配置文件 | 说明 |
hugo.toml / hugo.yaml / hugo.json | Hugo 新版配置格式（推荐） |
config.toml / config.yaml / config.json | Hugo 旧版配置格式 |
config/_default/ 目录 | Hugo 多环境配置方式 |
系统通过检测这些文件自动判断项目是否为 Hugo 项目。
部署步骤
1. 创建 Hugo 项目
hugo new site my-sitecd my-site
2. 添加
edgeone.json 配置文件（可选但推荐）// ./edgeone.json{"buildCommand": "hugo --minify","outputDirectory": "public"}
3. 在本地开发完相关的页面
4. 推送代码到 Git 仓库
5. 在 Pages 控制台关联仓库并部署
系统会自动检测到 Hugo 项目并完成构建部署。
Hugo 版本管理
Pages 预装了 Hugo Extended v0.147.5 作为默认版本, 支持 SCSS/SASS 编译。
版本优先级
按以下优先级确定使用的 Hugo 版本（从高到低）：
优先级 | 方式 | 说明 |
1（最高） | edgeone.json 的 hugoVersion 字段 | 项目级配置，推荐使用 |
2 | HUGO_VERSION 环境变量 | 运行时环境变量 |
3（最低） | 预装版本 | v0.147.5 |
方式一：通过 edgeone.json 指定版本（推荐）
在项目根目录的
edgeone.json 中添加 hugoVersion 字段：{"hugoVersion": "0.139.0","buildCommand": "hugo --minify","outputDirectory": "public"}
注意：
版本号支持带或不带
v 前缀，例如 "0.139.0" 和 "v0.139.0" 均可。方式二：通过环境变量指定版本
在 Pages 控制台的项目设置中，添加环境变量：
HUGO_VERSION=0.139.0
方式三：使用默认版本
如果未指定版本，系统将使用预装的 Hugo Extended v0.147.5。
构建配置
构建命令
在
edgeone.json 中通过 buildCommand 配置 Hugo 构建命令：{"buildCommand": "hugo --minify","outputDirectory": "public"}
常用的 Hugo 构建命令示例：
命令 | 说明 |
hugo | 默认构建 |
hugo --minify | 构建并压缩 HTML/CSS/JS |
hugo --minify --gc | 构建、压缩并清理未使用资源 |
hugo -e production | 使用 production 环境配置构建 |
hugo --baseURL https://example.com | 指定站点基础 URL |
输出目录
Hugo 默认输出目录为
public，请在 edgeone.json 中将 outputDirectory 设置为 public（或你自定义的输出目录）。
构建缓存
Pages 会自动管理 Hugo 的构建缓存，无需手动配置。
缓存机制
缓存目录：
resources/_gen。缓存内容：Hugo 图片处理结果、SCSS/SASS 编译产物等生成资源。
恢复时机：每次构建开始前自动恢复上次缓存。
保存时机：每次构建完成后自动保存。
缓存效果
利用
resources/_gen 缓存，重复构建时可跳过已处理的图片和已编译的样式文件，显著减少构建时间。
支持的配置格式
Hugo 支持多种配置文件格式，Pages 均能正确识别：
单文件配置
my-hugo-site/├── hugo.toml # 推荐├── content/├── layouts/└── static/
旧版单文件配置
my-hugo-site/├── config.toml # 旧版格式，仍然支持├── content/├── layouts/└── static/
多环境配置（目录方式）
my-hugo-site/├── config/│ └── _default/│ ├── hugo.toml│ ├── params.toml│ └── menus.toml├── content/├── layouts/└── static/
常见问题
1. 如何确认系统检测到了我的 Hugo 项目？
构建日志中会出现
Hugo project detected. 提示，并显示当前使用的 Hugo 版本，例如：Using Hugo v0.147.5
2. 构建报错提示 Hugo 版本不支持某功能怎么办？
检查你的 Hugo 主题或模板要求的最低版本，在
edgeone.json 中指定对应版本：{"hugoVersion": "0.128.0"}
3. Hugo 安装失败（退出码 14）怎么办？
可能原因：
指定的 Hugo 版本号无效（不存在该版本的 Release）
网络问题导致下载失败
解决方法：
确认版本号正确，可在 Hugo Releases 页面查看所有可用版本
如果是临时网络问题，重新触发构建即可
4. 为什么使用的是 Hugo Extended 版本？
Hugo Extended 版本内置了对 SCSS/SASS 的编译支持，大多数 Hugo 主题都依赖此功能。Pages 始终安装 Extended 版本，确保与主流主题的兼容性。
5. Hugo 项目需要 package.json 吗？
不需要。Hugo 项目的检测独立于 Node.js 生态，系统通过 Hugo 配置文件（如
hugo.toml）进行检测。但如果你的项目同时使用了 npm 包（如 PostCSS），可以同时包含 package.json。6. 如何清除构建缓存？
如果遇到缓存导致的构建异常，可以在构建命令中添加清理步骤：
{"buildCommand": "rm -rf resources/_gen && hugo --minify","outputDirectory": "public"}
完整配置示例
最小配置
项目根目录只需包含 Hugo 配置文件（如
hugo.toml），系统将使用默认版本和默认构建行为。推荐配置
edgeone.json：{"hugoVersion": "0.147.5","buildCommand": "hugo --minify","outputDirectory": "public"}
高级配置（多环境）
edgeone.json：{"hugoVersion": "0.147.5","buildCommand": "hugo --minify -e production","outputDirectory": "public"}