Hugo 站点构建生命周期

Hugo 根据配置、挂载文件、内容元数据、模板和资源构建站点。文件放置属于数据模型的一部分，因为它决定页面类型、捆绑边界和模板查找。

选择构建配置 #

除非 --destination 更改目标，否则 hugo 命令执行生产构建并写入 public/。 hugo server 提供开发构建并监视其依赖项：

hugo --environment production
hugo server --environment development

环境默认值不同：hugo 使用 production，而 hugo server 使用 development。 --environment 或 HUGO_ENVIRONMENT 选择显式环境。项目可以使用一个配置文件（如 hugo.toml）、逗号分隔的 --config 列表，或 config/_default/ 和 config/<environment>/ 下的分层文件。后面且更具体的设置会覆盖前面的设置，因此构建诊断应记录命令和环境，而不仅是仓库修订版本。

模块挂载会在收集内容之前解析。挂载可以将多个源目录组合到虚拟的 content、assets、static 或 layouts 树中；因此只检查物理 content/ 目录可能会遗漏构建输入。

分类页面、分区、分类法和资源 #

Hugo 根据文件名和目录结构推导页面类型：

content/_index.md 为主页提供内容和元数据。
分区目录可以包含 _index.md，它会为该分区创建分支捆绑。
包含 index.md 的目录是叶捆绑。其下的 Markdown 文件是页面资源，而不是独立页面。
其他内容文件会成为其所在分区中的普通页面。
配置的分类法会根据 front matter 生成分类法页面和术语页面。

分支捆绑可以包含子页面和分区。叶捆绑表示一个页面及其资源，例如图像、数据或生成文件：

text

content/
  posts/
    _index.md
    canvas/
      index.md
      diagram.svg

posts/canvas/ 中的页面可以通过 .Page.Resources 解析 diagram.svg。static/ 下的文件遵循不同路径：Hugo 将它们复制到目标位置，而不会将它们暴露为可处理页面或全局资源。

根据 Front Matter 和级联构建页面 #

Front matter 提供 title、date、draft、outputs、layout、type、分类法和自定义参数等字段。Hugo 会将这些值与根据路径、语言、站点配置和 Git 元数据推断的默认值组合起来。

站点配置中的 cascade 或分支捆绑的 _index.md 会为后代提供 front matter 默认值：

yaml

cascade:
  type: docs
  params:
    audience: developers

后代 front matter 可以覆盖级联值。级联还可以使用路径、页面类型、环境或语言的目标选择器。由于最终页面对象反映每个适用层级，因此意外的 .Type 或 .Params 值应沿内容文件及其祖先级联进行追踪。

Hugo 还会在构建页面时关联翻译、别名、页面资源、分类术语和分区祖先。模板使用完成的页面图，而不是独立解析文件。

转换内容并渲染输出 #

概念上的构建路径是：

加载配置、模块、数据、翻译、模板和挂载文件。
构建页面和资源图，包括分区和分类法。
解析内容，展开 shortcode，并调用 Markdown 渲染钩子。
通过匹配的模板渲染每种启用的输出格式。
处理请求的资源，并发布渲染文件和静态文件。

模板求值可以惰性请求内容或资源转换，因此这些阶段是依赖关系，而不是内部 goroutine 顺序的承诺。生成 .Content 时会运行 shortcode；外层页面模板随后将结果放入 HTML、RSS、JSON 或其他输出中。

输出格式按站点和页面类型配置。同一内容可以生成多个文件：

yaml

outputs:
  home:
    - HTML
    - RSS
    - JSON

模板查找会考虑页面类型、类型、分区、布局、语言和输出格式。HTML 单页布局等特定格式模板不会自动服务 RSS 输出。诊断意外回退时，应使用 Hugo 的模板指标或警告运行，而不要假设某个硬编码文件名。

处理缓存和开发构建 #

Hugo 会缓存下载的模块、远程资源和已处理资源。资源指纹使有效的缓存结果可以复用，而模板或源代码变更会使其依赖项失效。项目有意使用该缓存时，可以在 CI 中提交或恢复 resources/_gen/ 下的生成文件，但它们是派生产物，而不是源内容。

hugo server 将依赖图保存在内存中，监视变更，并使用快速渲染行为重建交互式开发所需的页面。它通常从内存提供服务，而不是复现 public/ 中的准确文件。需要完整开发重渲染时使用 --disableFastRender，仅在检查磁盘上的服务器输出时使用 --renderToDisk。

干净的生产构建仍是发布检查，因为开发缓存和增量渲染可能隐藏未声明的依赖：

hugo --gc --cleanDestinationDir --environment production

--cleanDestinationDir 会删除目标目录中 Hugo 在当前构建中不生成的文件，而 --gc 会删除未使用的缓存条目。这两个选项都不能修复错误的内容分类或模板查找；这些行为由项目结构和配置决定。