Hugo 全局函数（page 与 site）完全指南：在任何模板上下文中访问页面与站点数据-北京尧图网络

开发工具前端CLI【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址https://gitcode.com/gh_mirrors/hu/hugo点击查看免费下载Hugo 模板系统除了把Page、Site对象作为数据上下文.传入模板外还提供了一组全局函数Global functions让你在任意上下文——包括嵌套的 partial、render hook 中——都能稳定地拿到“当前页面”与“当前站点”。本篇指南以 Hugo 文档 functions/global 这一章节为核心结合仓库源码tpl/page/init.go、tpl/site/init.go、resources/page/site.go等讲透page与site两个全局函数的用法、等价写法、底层实现以及两个最容易踩的坑顶层上下文与模板缓存读完即可在真实站点模板中安全、正确地使用它们。一、什么是全局函数page与site在 Hugo 文档体系中functions/global是一个独立的函数分类目录其章节描述只有一句话Use these global functions to access page and site data.使用这些全局函数访问页面与站点数据。它下属两个实际函数函数返回类型作用文档正文pagepage.Page返回当前页面的Page对象可从任何上下文访问page 文档sitepage.siteWrapper返回当前站点的Site对象可从任何上下文访问site 文档从源码角度看两者都是通过 Hugo 的“模板函数命名空间”机制注册的全局函数tpl/page/init.go中const name pagetpl/site/init.go中const name site均通过internal.AddTemplateFuncsNamespace(f)注册。因此你在模板的任何位置都可以直接书写{{ page.XXX }}或{{ site.XXX }}无需像普通函数那样带包名前缀如partials.IncludeCached。二、page全局函数随时拿到当前页面1. 基本用法三种等价写法当模板顶层上下文本身就是Page对象时以下三种写法完全等价见 page 文档的 Usage 一节{{ .Params.foo }} {{ .Page.Params.foo }} {{ page.Params.foo }}Hugo 在渲染顶层模板如baseof.html、single.html、home.html时几乎总会把Page作为数据上下文传入因此.通常可以直接访问当前页面。唯一的例外是多主机multihostsitemap 模板——它没有 Page 作为上下文。当你在 partial、render hook 等深层嵌套中无法或不方便通过.访问Page时page函数就派上用场{{ page.Params.foo }}这正是全局函数的价值从任意上下文、任意模板中获取当前页面对象。2. 底层实现从渲染上下文context中取 Pagepage函数并不是凭空猜测“当前页面”而是从 Gocontext.Context中显式取出。看 tpl/page/init.go 的实现f : func(d *deps.Deps) *internal.TemplateFuncsNamespace { ns : internal.TemplateFuncsNamespace{ Name: name, Context: func(ctx context.Context, args ...any) (any, error) { v : tpl.Context.Page.Get(ctx) if v nil { // The multilingual sitemap does not have a page as its context. return nil, nil } return v.(page.Page), nil }, } return ns }这条调用链是渲染页面前Hugo 把当前Page注入渲染上下文。核心代码在 tpl/tplimpl/templatestore.go 的PrepareTopLevelRenderCtxfunc (t *TemplateStore) PrepareTopLevelRenderCtx(ctx context.Context, p page.Page) context.Context { if p ! nil { ctx tpl.Context.Page.Set(ctx, p) } ... }真正渲染页面时调用它在 hugolib/site.go 的renderAndWritePage中ctx : s.TemplateStore.PrepareTopLevelRenderCtx(context.Background(), p)别名页面的渲染同样走此流程见 hugolib/alias.go。上下文键定义在 tpl/template.gocontextKeyPage对应Context.Page这个ContextDispatcher。而page全局函数正是通过tpl.Context.Page.Get(ctx)读取它。从源码结构看这套机制保证了只要当前模板渲染确实发生在某个页面渲染流程内page就一定能取到该页面的Page对象若上下文里没有注入 Page如多语言 sitemap 场景函数返回nil, nil而不是报错。3. 常见坑一注意顶层上下文page函数访问的是传入顶层模板的那个 Page 对象而不是你在range中迭代到的页面。文档中给出了非常典型的一例。内容结构如下content/ ├── posts/ │ ├── post-1.md │ ├── post-2.md │ └── post-3.md └── _index.md -- title is My Home Page首页模板home中这样写{{ range site.Sections }} {{ range .Pages }} {{ page.Title }} {{ end }} {{ end }}渲染结果是My Home Page My Home Page My Home Page原因就在上面的实现细节page读取的是渲染上下文里注入的那个 Page这里是 home 模板的_index.md标题 My Home Page而range只是改变了点.指向的迭代值并不会改变 context 中的 Page。在循环体内想访问“当前迭代页面”应使用.或.Title、.LinkTitle而不是page。4. 常见坑二注意模板缓存文档明确警告见 page 文档的 Note 与 Examples 部分不要在以下场景使用page全局函数Shortcodes短代码被 shortcode 调用的 partial 模板被partialCached缓存起来的 partial 模板原因Hugo 会缓存渲染过的 shortcode。如果一个页面的内容在两个或更多模板中被渲染而 shortcode 内部使用了page函数那么缓存下来的 shortcode 输出可能是错误的。文档给出了具体场景section 模板中调用.Summary详见 page.Summary 方法文档{{ range .Pages }} h2a href{{ .RelPermalink }}{{ .LinkTitle }}/a/h2 {{ .Summary }} {{ end }}调用Summary时Hugo 会渲染页面内容包括其中的 shortcode。此时若 shortcode 内用了page它取到的是section 页面的 Page 对象而非内容页面的。更麻烦的是由于 Hugo 并发渲染、渲染顺序不可控如果 section 页面先于内容页面渲染缓存下来的 shortcode 结果就会是错误的。这一点同样可以从前文源码验证——page的值完全取决于渲染上下文中当前注入的是哪个 Page而缓存机制会把第一次渲染的结果复用给后续所有调用。[!NOTE] 在这三种场景中请改用显式传入的上下文.或$来访问页面对象避免依赖page全局函数。三、site全局函数随时拿到当前站点1. 基本用法与.Site、$.Site的对比site函数返回Site对象与上下文无关见 site 文档{{ site.Params.foo }}当Site对象已在上下文中时你同样可以用以下两种传统写法!-- current context -- {{ .Site.Params.foo }} !-- template context -- {{ $.Site.Params.foo }}文档给出的建议很直接无论Site对象是否在上下文中都请统一使用全局site函数这样能简化模板——你不必再关心当前点.指向的是 Page、Site 还是某个迭代值也不必在 partial 里纠结用.Site还是$.Site。2. 底层实现包装后的 Site 接口看 tpl/site/init.gof : func(d *deps.Deps) *internal.TemplateFuncsNamespace { s : page.WrapSite(d.Site) ns : internal.TemplateFuncsNamespace{ Name: name, Context: func(cctx context.Context, args ...any) (any, error) { return s, nil }, } // We just add the Site as the namespace here. No method mappings. return ns }site函数直接返回page.WrapSite(d.Site)的包装对象类型即为page.siteWrapper。包装器定义在 resources/page/site.go它持有一个内部Site并逐方法委托delegate同时通过Key()返回语言标识并实现了额外的identity相关内部接口。Site接口resources/page/site.go暴露了模板中最常用的一批方法例如站点基础信息Title()、BaseURL()、Copyright()、Language()、Languages()、Lastmod()页面集合Pages()、RegularPages()、AllPages()、Sections()、Home()、GetPage(ref...)配置与数据Params()、Param(key)、Config()、Data()、Menus()、Taxonomies()、MainSections()多站点支持Sites()、Current()、IsDefault()、LanguagePrefix()、ServerPort()构建信息Hugo()返回HugoInfo因此模板中可以放心书写诸如{{ site.Title }}、{{ site.BaseURL }}、{{ site.Menus.main }}、{{ site.GetPage /about }}等表达式。3. 与page的差异无缓存陷阱与page不同site函数的取值与渲染上下文、渲染顺序无关——它在函数命名空间初始化时一次性包装了d.Site之后每次调用都返回同一个包装对象。所以site没有“顶层上下文”和“缓存污染”这两类问题可以在 shortcode、partial含partialCached、render hook 中放心使用。这也是为什么官方文档建议模板中统一采用site。四、实战选型page、site 与.、$该怎么选综合两个函数的语义与源码实现给出如下选型建议场景推荐写法理由顶层模板上下文是 Page访问当前页面{{ .Params.foo }}直接、直观顶层模板访问站点信息{{ site.Params.foo }}与上下文解耦官方推荐partial / render hook访问当前页面{{ page.Params.foo }}上下文不可靠时兜底partial / render hook访问站点信息{{ site.Title }}任何位置都可用shortcode 内部访问“调用它的页面”传入参数如{{ .Inner }}所在页面经GetPage/参数传递page在此场景可能命中缓存错误range循环内访问“迭代到的页面”{{ .Title }}page始终指向顶层页面核心原则一句话site全局函数可无条件使用page全局函数只应在“确认不会被缓存复用”的模板层级使用且它总是代表顶层模板的当前页面而不是循环中的迭代对象。五、可验证的源码与文档路径全局函数章节入口docs/content/en/functions/global/_index.mdpage函数文档与示例docs/content/en/functions/global/page.mdsite函数文档docs/content/en/functions/global/site.mdpage函数实现从 context 取 Pagetpl/page/init.gosite函数实现WrapSite 包装tpl/site/init.goSite接口与siteWrapper委托实现resources/page/site.go渲染上下文与Context.Page调度器tpl/template.go渲染前注入 Page 的PrepareTopLevelRenderCtxtpl/tplimpl/templatestore.go页面渲染调用链renderAndWritePagehugolib/site.gopartialCached函数说明docs/content/en/functions/partials/IncludeCached.mdSummary方法说明docs/content/en/methods/page/Summary.md结语page与site是 Hugo 模板体系中最常用的两个全局函数前者让你在深层嵌套中依然能定位“当前页面”后者让你在任何位置拿到“当前站点”。理解它们的关键在于认清实现本质page读取的是渲染上下文中注入的 Page因此有顶层上下文与缓存两大陷阱而site返回的是初始化时包装好的站点对象因此无条件安全。记住本文的选型表格与两条官方警告你就能写出既简洁又稳健的 Hugo 模板。赞分享开发工具前端CLI【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址https://gitcode.com/gh_mirrors/hu/hugo点击查看免费下载相关推荐43秒无缝长视频ComfyUI-WanVideoWrapper单卡跑通Context Window长视频生成43秒无缝长视频ComfyUI WanVideoWrapper单卡跑通Context Window长视频生成单卡显存不到5GB一口气生成1025帧连贯视频人工智能大模型媒体生成如何让 AI 操作真实已登录浏览器BrowserSkill 10 分钟上手指南如何让 AI 操作真实已登录浏览器BrowserSkill 10 分钟上手指南 BrowserSkill 是一款让 AI 智能体直接操作你真实、已登录的 Ch人工智能AI 应用AI 技能浏览器控制dsh-pluginHugo 模板上下文Context完全指南理解点号 . 与模板数据流Hugo 模板上下文Context完全指南理解点号 . 与模板数据流 Hugo 的模板系统建立在 Go 标准库 text/template 与 html/开发工具前端CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Hugo 全局函数（page 与 site）完全指南：在任何模板上下文中访问页面与站点数据

相关推荐

Qt网络编程实战：UDP、TCP与HTTP核心类详解与踩坑指南

Python音频可视化：音量与频谱柱状图实现全解析

三大 AI IDE 首周补全质量盲测汇总与综合得分榜：TaoToken 统一 Key 接入 Cursor/Windsurf/Copilot 的实测记录

更多资讯

海外仓平台资质认证全梳理：哪些认证值得卖家盯

拆解 Intern-S2-397B 的“科学大脑“：记忆解码器+可视化预训练是怎么协同的

数据流中位数双堆解法：从原理到工程实战

文档与代码的一致性，靠 AI 还是靠人？Spec Kit 给出的答案为什么在社区里吵翻了

GC10-DET：金属表面缺陷检测的工业级基准数据集

基于Spring Boot的雪具租赁系统开题答辩全复盘

今日更新

再见，SSE！你好，Streamable HTTP！轻松开发 Streamable HTTP MCP Server 并接入 TaoToken

工业软件标准化路线图：国产替代的落地施工图

VCMI安卓版实操指南：原生运行英雄无敌3的3步技术落地

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？