企业官网建设流程全解析

• 开发工具
• 前端
• CLI

导读

本篇技术指南围绕 Hugo 中 Shortcode 上下文提供的RelRef方法展开，讲解如何通过一个 options map 参数，把任意页面的路径解析为站点内部的相对 URL（relative URL），并支持跨语言、跨输出格式的精确定位。读完本文，你将掌握RelRef的完整参数体系、与 Page 方法RelRef及relrefshortcode 的关系、错误处理策略，以及它在多语言站点内部链接场景中的实战用法。

什么是 Shortcode 的 RelRef 方法

在 Hugo 的模板体系中，shortcode 在被调用时，其内部模板会获得一个以.为根节点的上下文。该上下文提供了一批方法，其中就包括RelRef。根据 docs/content/en/methods/shortcode/RelRef.md 的定义，该方法：

• 返回类型：string
• 签名：SHORTCODE.RelRef OPTIONS

即它接收一个 options map 参数，返回目标页面的相对 URL。所谓相对 URL，指的是不包含协议和主机名（如https://example.org）的路径形式，例如/en/books/book-1/。

与 Page.RelRef 的关系

Shortcode 的RelRef实际上是 Page 方法RelRef的一个便捷封装。在 hugolib/shortcode.go 中可以看到它的底层实现：

// RelRef is a shortcut to the RelRef method on Page. It passes itself as a context func (scp *ShortcodeWithPage) RelRef(args map[string]any) (string, error) { return scp.Page.RelRefFrom(args, scp) }

也就是说，shortcode 内部的RelRef方法会把当前 shortcode 自身作为解析的相对基准（source）传给RelRefFrom，从而确保相对路径的解析总是以当前页面为出发点。这也意味着，在 shortcode 模板里调用RelRef与在普通页面模板里调用Page.RelRef，其解析逻辑完全一致，只是上下文对象不同。

从源码看，最终解析动作落在 hugolib/page__ref.go 的relRef方法上，它内部通过siteRefLinker.refLink(args.Path, source, true, args.OutputFormat)完成查询，第三个参数true即表示输出相对 URL（而Ref方法对应的ref分支则传false，输出绝对 URL）。

Options 参数详解

RelRef方法只接受一个参数：options map。map 中支持的键来自通用的 "ref-and-relref-options" 定义（见 docs/content/en/_common/ref-and-relref-options.md）：

其中path是必填项，lang与outputFormat均为可选项。

底层参数解析

在 hugolib/page__ref.go 中，options map 通过mapstructure.WeakDecode被解码为refArgs结构体（字段为Path、Lang、OutputFormat）。这里有一个关键行为值得注意：当指定了lang且与当前站点语言不同时，Hugo 会在站点集合（p.p.s.h.Sites）中查找对应语言的站点；如果找不到，会调用logNotFound记录错误，并返回notFoundURL。这解释了为什么跨语言引用要求目标语言确实存在于站点配置中。

使用示例

以下示例展示的是站点英文版本中的某个页面调用RelRef方法后的渲染结果：

{{ $opts := dict "path" "/books/book-1" }} {{ .RelRef $opts }} → /en/books/book-1/ {{ $opts := dict "path" "/books/book-1" "lang" "de" }} {{ .RelRef $opts }} → /de/books/book-1/ {{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }} {{ .RelRef $opts }} → /de/books/book-1/index.json

三个示例展示了三种典型用法：

1. 仅指定path：返回当前语言（此处为英文）下目标页面的相对 URL/en/books/book-1/；
2. 指定path+lang：跨语言解析，返回德语版本页面的相对 URL/de/books/book-1/；
3. 指定path+lang+outputFormat：进一步指定输出格式为json，得到/de/books/book-1/index.json，即该页面 JSON 格式输出的地址。

在 shortcode 模板中的实际写法

RelRef是 Shortcode 上下文的方法，因此它通常出现在自定义 shortcode 的模板文件中（位于layouts/_shortcodes/目录）。例如在一个名为link-to的自定义 shortcode 模板中，可以这样写：

{{ $opts := dict "path" (.Get 0) }} <a href="{{ .RelRef $opts }}">目标页面</a>

调用方式：

{{< link-to "/books/book-1" >}}

这样渲染出的<a>标签的href就是目标页面的相对 URL，能够天然适配站点的baseURL子路径部署场景（例如部署在https://example.org/docs/之下时，相对 URL 依然正确）。

错误处理

默认情况下，如果 Hugo 无法解析path指定的路径，会抛出错误并导致构建失败。这一默认行为保证了站内链接的有效性——任何一个失效的内部链接都会在构建期被暴露出来。

如果希望在链接无法解析时构建继续，可以在项目配置文件hugo.toml（或hugo.yaml/hugo.json）中做如下调整（参见 docs/content/en/_common/ref-and-relref-error-handling.md）：

refLinksErrorLevel = 'warning' refLinksNotFoundURL = '/some/other/url'

两个配置项的含义：

• refLinksErrorLevel = 'warning'：把无法解析路径时的错误降级为警告，构建不会失败；
• refLinksNotFoundURL = '/some/other/url'：指定路径无法解析时返回的兜底 URL。

从源码看，这一兜底行为在 hugolib/page__ref.go 中体现为：当解码参数失败或目标语言站点不存在时（s == nil），relRef直接返回p.p.s.siteRefLinker.notFoundURL，即配置中所设置的兜底 URL。

RelRef 方法与 relref shortcode 的区别

除了 Shortcode 上下文的方法RelRef之外，Hugo 还内置了名为relref的 shortcode（用法见 docs/content/en/shortcodes/relref.md），两者的解析规则、参数（path/lang/outputFormat）与错误处理完全相同。主要区别在于使用场景：

• RelRef（方法）：在自定义 shortcode 模板或普通模板代码中，通过.RelRef以编程方式调用，适合需要动态构造 options map 的场景；
• relref（内置 shortcode）：直接在 Markdown 内容中通过{{% relref ... %}}语法调用，通常为 Markdown 链接提供目标地址，例如：

Link C

渲染为：

<a href="/de/books/book-1/">Link C</a>

需要留意的是，relrefshortcode 的官方文档特别指出：在处理 Markdown 时，该 shortcode 已趋于过时（obsolete），官方推荐使用内置的链接渲染钩子（embedded link render hook）来正确解析 Markdown 链接目标。不过，Shortcode 上下文上的RelRef方法在自定义 shortcode 模板编程中依然是有效且常用的手段。

与 Page.RelRef 及 urls.RelRef 的对照

RelRef相关能力在 Hugo 中还有另外两个入口，方便读者对照查阅：

• Page 方法RelRef：见 docs/content/en/methods/page/RelRef.md，在页面模板中使用.RelRef，其参数与行为与 Shortcode 版本一致；
• 模板函数urls.RelRef：见 docs/content/en/functions/urls/RelRef.md，它以函数形式提供同样的能力，实现在 tpl/urls/urls.go，其返回Page.RelRef的结果。

对应的Ref系列（返回绝对 URL）也可参照 docs/content/en/methods/shortcode/Ref.md。简言之：需要相对 URL 用RelRef，需要绝对 URL（含协议与主机名）用Ref，其余参数规则完全一致。

小结

• Shortcode 上下文的RelRef方法接收一个 options map，必填path，可选lang与outputFormat；
• 它封装了 Page 的RelRefFrom逻辑，以当前 shortcode 所在页面为相对解析基准，底层实现在 hugolib/page__ref.go；
• 相对 URL 结果天然适配子路径部署与多语言站点；
• 默认情况下无法解析的路径会导致构建失败，可通过refLinksErrorLevel与refLinksNotFoundURL配置降级为警告并指定兜底 URL；
• 在 Markdown 内容中优先考虑内置链接渲染钩子，在 shortcode 模板编程中则直接使用RelRef方法。

• 开发工具
• 前端
• CLI