开发工具前端CLI【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址https://gitcode.com/gh_mirrors/hu/hugo点击查看免费下载本指南围绕 Hugo 中获取“全维度站点集合”的Sites方法展开涵盖其返回值类型、三级排序规则、在 multilingual multiversion 项目中的实战用法以及 v0.156.0 起的弃用迁移路径。读完本文你将能正确使用hugo.Sites/hugo.Sites.Default遍历语言、版本、角色三个维度上的全部站点并理解其底层实现机制。一、Sites 方法是什么Sites是 Hugo 站点对象Site提供的一个方法用于返回所有维度language、version、role上的全部站点集合。在模板中通过SITE.Sites调用返回类型为page.Sites见 Sites.md 的 front matter 定义returnType: page.Sites、signatures: [SITE.Sites]。在单个站点site的模板上下文里Sites集合让开发者能够从当前语言/版本的视角一次性访问整个站点矩阵——包括其他语言、其他版本、其他角色的站点。注意Sites是无参方法直接{{ .Sites }}即可得到集合对象通常配合range遍历使用。二、重要变更v0.156.0 起已弃用该文档明确标注了弃用状态deprecated 2026-02-18 in v0.156.0Use thehugo.Sitesfunction instead.即从 v0.156.0 开始模板中应改用全局函数hugo.Sites替代Site.Sites/Page.Sites。新函数对应的完整文档位于 hugo/Sites.md标注为new-in 0.156.0。迁移对应关系旧写法已弃用新写法推荐{{ .Site.Sites }}{{ hugo.Sites }}{{ .Sites }}页面上下文{{ hugo.Sites }}从源码看旧方法仍保留兼容但会触发弃用告警。在 hugolib/site.go 中// Returns all sites for all dimensions. // Deprecated: Use hugo.Sites instead. func (s *Site) Sites() page.Sites { s.h.printSiteSitesDeprecationInit.Do(func() { hugo.Deprecate(.Site.Sites and .Page.Sites, Use hugo.Sites instead., v0.156.0) }) return slices.Collect(s.h.allSitesInterface(nil)) }可以看到它通过printSiteSitesDeprecationInit只输出一次弃用提示随后仍委托给底层的allSitesInterface完成实际遍历因此功能语义与hugo.Sites完全一致区别仅在告警与调用入口。三、返回集合的排序规则Sites返回的集合遵循层级排序hierarchical sort每个后续维度作为前一维度的 tie-breaker。该规则定义在共享文档 sites-collection.md 中具体如下Language语言按weight升序排序若weight相同或未定义回退到字典序lexicographical order。Version版本在语言排序之后按weight升序若并列Hugo 默认采用语义版本降序descending semantic sort。Role角色最后按weight升序排序最终回退到字典序。也就是说集合顺序 先按语言排再按版本排最后按角色排。理解这一顺序对依赖遍历顺序输出导航、语言切换器或版本选择器至关重要。四、实战配置多语言 多版本项目以 hugo/Sites.md 中的完整配置为例一个包含两种语言de、en和三个版本v1.0.0、v2.0.0、v3.0.0的项目配置如下defaultContentLanguage en defaultContentLanguageInSubdir true defaultContentVersionInSubdir true [languages.de] contentDir content/de direction ltr label Deutsch locale de-DE title Projekt Dokumentation weight 1 [languages.en] contentDir content/en direction ltr label English locale en-US title Project Documentation weight 2 [versions.v1.0.0] [versions.v2.0.0] [versions.v3.0.0]关键参数说明defaultContentLanguage en声明默认语言决定hugo.Sites.Default落在哪个语言上对应配置文档中的defaultContentLanguage项defaultContentLanguageInSubdir true默认语言内容也放在子目录URL 中体现为/en/前缀defaultContentVersionInSubdir true默认版本内容也放在子目录URL 中体现为/v3.0.0/前缀每个[languages.xx]块定义一种语言contentDir指定内容目录、weight控制排序权重、title/label/locale用于展示与本地化每个[versions.x.y.z]块声明一个版本维度未显式配置 weight 时版本并列Hugo 按语义版本降序排列即 v3.0.0 排最前。五、模板用法与输出示例1. 遍历全部站点下面的模板来自官方文档示例遍历所有站点为每个站点的首页生成链接同时显示站点标题和版本名ul {{ range hugo.Sites }} lia href{{ .Home.RelPermalink }}{{ .Title }} {{ .Version.Name }}/a/li {{ end }} /ul配合上文配置输出结果为注意顺序符合排序规则德语 weight 更小故排前版本按语义降序 v3.0.0 → v1.0.0ul lia href/v3.0.0/de/Projekt Dokumentation v3.0.0/a/li lia href/v2.0.0/de/Projekt Dokumentation v2.0.0/a/li lia href/v1.0.0/de/Projekt Dokumentation v1.0.0/a/li lia href/v3.0.0/en/Project Documentation v3.0.0/a/li lia href/v2.0.0/en/Project Documentation v2.0.0/a/li lia href/v1.0.0/en/Project Documentation v1.0.0/a/li /ul2. 定位默认站点hugo.Sites.Default返回默认站点——即默认语言defaultContentLanguage、默认版本、默认角色交汇处的站点与其在集合中的位置无关{{ with hugo.Sites.Default }} a href{{ .Home.RelPermalink }}{{ .Title }}/a {{ end }}对于上文配置该模板渲染出英文 v3.0.0 站点的首页链接。尽管三个德语站点因weight更小排在最前但defaultContentLanguage en决定了默认站点是英文站点。注意Default需要用with包裹以处理空值场景。3. 旧 API 写法v0.156.0 前在升级前等价的旧写法是{{ range .Site.Sites }}/{{ .Site.Sites.Default }}。由于新函数与旧方法共享底层实现迁移时只需机械替换调用入口即可输出结果完全一致。六、源码实现解析1. 全局函数入口hugo.Sites由hugoSitesSitesProvider提供定义于 hugolib/hugo_sites.go// hugoSitesSitesProvider is a wrapper that implements page.SitesProvider. // This avoids naming conflict with HugoSites.Sites field. type hugoSitesSitesProvider struct { h *HugoSites } func (sp hugoSitesSitesProvider) Sites() page.Sites { return slices.Collect(sp.h.allSitesInterface(nil)) }注释点明了设计动机该包装类型实现了page.SitesProvider接口避免与HugoSites.Sites字段命名冲突。2. 核心遍历逻辑新旧两种入口最终都汇聚到allSitesInterfacehugolib/hugo_sites.gofunc (h *HugoSites) allSitesInterface(include func(s page.Site) bool) iter.Seq[page.Site] { if include nil { include func(s page.Site) bool { return true } } return func(yield func(s page.Site) bool) { for _, v : range h.sitesVersionsRoles { for _, r : range v { for _, s : range r { if !include(s) { continue } // Site() returns a wrapped version of the site that only exposes the page.Site interface. if !yield(s.Site()) { return } } } } } }从该实现可以推断出站点的组织结构是嵌套的sitesVersionsRoles语言 → 版本 → 角色三维矩阵allSitesInterface以三重循环展开它这与文档中“所有维度language/version/role”的描述一一对应返回给模板的每个元素通过s.Site()包装只暴露page.Site接口保证模板层无法触碰内部实现函数签名支持传入include过滤函数为内部按维度筛选站点预留了能力传入nil时返回全部站点。3. 站点包装层resources/page包中siteWrapper.Sites()resources/page/site.go直接透传给内部站点对象func (s *siteWrapper) Sites() Sites { return s.s.Sites() }而page层面如 resources/page/page.go 的nopHugoSitesProvider也实现了同名方法说明Sites是page.Site接口体系中的标准成员。七、相关 API 与使用建议Site.IsDefault判断当前站点是否为全维度默认站点源码位于 hugolib/site.go即“Returns whether this site is the default across all dimensions”常与Sites搭配实现“仅在默认站点输出”的逻辑Site.Home获取站点首页页面对象Sites遍历中常用.Home.RelPermalink生成链接Site.Version获取站点所属版本信息多版本站点中用于展示版本名Site.Language获取语言信息多语言切换器中常与Sites联用。升级建议若你的模板仍在使用{{ .Site.Sites }}或{{ .Sites }}请尽快迁移到hugo.Sitesv0.156.0以避免弃用告警并在未来版本中保持兼容多语言、多版本站点矩阵的排序、默认站点判定规则在新旧 API 间完全一致可直接替换无需调整业务逻辑。赞分享开发工具前端CLI【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址https://gitcode.com/gh_mirrors/hu/hugo点击查看免费下载相关推荐Hugo hugo.Sites 集合Language / Version / Role 三维排序规则与默认站点详解Hugo hugo.Sites 集合Language / Version / Role 三维排序规则与默认站点详解 导读 本文围绕 Hugo 模板函数 hug开发工具前端CLIHugo hugo.Sites 函数详解:跨语言、版本与角色维度的站点集合访问Hugo hugo.Sites 函数详解:跨语言、版本与角色维度的站点集合访问 Hugo 0.156.0 引入了 hugo.Sites 模板函数,用于在构建多语开发工具前端CLIHugo 多语言站点中的 Pages.ByLanguage 方法按语言权重排序页面集合的完整指南Hugo 多语言站点中的 Pages.ByLanguage 方法按语言权重排序页面集合的完整指南 导读 ByLanguage 是 Hugo 中作用于 Page开发工具前端CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考