文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>边缘安全加速平台 EO>Pages>框架指南>前端>Hugo

Hugo

最近更新时间：2026-04-09 11:41:11

我的收藏

本页目录：

概述

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-site
cd 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"
}
中国站