Hugo 中 unmarshal 模板函数完全指南：从字符串与资源解析 JSON、YAML、TOML、CSV 与 XML

• 开发工具
• 前端
• CLI

在 Hugo 模板中，"unmarshal"（反序列化）意味着把一段序列化数据（如 JSON、YAML、TOML、CSV、XML）转换成一个可直接通过.key或index访问的 map 或 slice 数据结构，这正是 docs/content/en/quick-reference/glossary/unmarshal.md 所给出的定义。本指南以该词条为线索，结合transform.Unmarshal函数的官方文档与源码实现，系统讲解其支持的数据格式、五个配置选项（delimiter、comment、format、lazyQuotes、targetType），以及针对字符串、全局资源、页面资源、远程资源的完整实战用法。读完本文，你将能够在 Hugo 模板中可靠地把外部数据文件解析成可渲染的数据结构，并理解格式自动推断与结果缓存背后的底层原理。

什么是 unmarshal

Hugo 官方术语表中对unmarshal（动词）的定义是：

将序列化对象转换为数据结构（data structure）的过程。例如，将一个 JSON 文件转换为可以在模板中访问的 map。

与之相对的是marshal（序列化），即把数据结构编码为文本。在 Hugo 模板体系中，承担反序列化职责的核心函数是transform.Unmarshal，其别名为unmarshal，注册于transform命名空间，具体映射见 tpl/transform/init.go。

{{ "hello = \"Hello World\"" | transform.Unmarshal }} → map[hello:Hello World]

这个简单示例中，一段 TOML 格式的字符串被解析成了一个可直接读取键值的 map。源码注释对函数的概括是（见 tpl/transform/unmarshal.go）：

• 输入可以是string、json.RawMessage或一个Resource；
• 支持格式为 JSON、TOML、YAML 和 CSV（实际还支持 XML 与 org，详见下文）；
• 可选地以 options map 作为第一个参数。

函数签名与返回值

根据 docs/content/en/functions/transform/Unmarshal.md 中的参数定义：

参数个数限制为 1 或 2：一个参数时直接传入数据；两个参数时第一个必须是 options map（map[string]any），否则返回错误"first argument must be a map"（见 tpl/transform/unmarshal.go）。

支持的格式与自动推断机制

transform.Unmarshal支持的格式定义在 parser/metadecoders/format.go：org、json、toml、yaml、csv、xml六种。官方文档明确说明支持 CSV、JSON、TOML、YAML 和 XML。

从字符串内容推断格式

当传入字符串且未指定format选项时，Hugo 通过FormatFromContentString自动检测格式，检测逻辑（见 parser/metadecoders/format.go）是依次查找首个出现的特征字符，出现位置最靠前的格式胜出：

• 分隔符（Delimiter，默认,）→ CSV
• {→ JSON
• :→ YAML
• <→ XML
• =→ TOML

检测不到任何特征字符时返回""（未知格式），最终在函数中报错"unknown format"。

从资源媒体类型推断格式

当输入是Resource且未指定format时，Hugo 使用资源媒体类型（MediaType）的后缀（Suffixes）来推断格式（tpl/transform/unmarshal.go）。若资源的 MIME 类型不受支持（例如text/calendar），会返回错误MIME %q not supported——这一点在测试用例中有明确验证（tpl/transform/unmarshal_test.go）。

从源码结构可以推断，对 YAML 的解码还带有一层安全防护：validateAliasLimitForCollections会根据数据大小限制集合节点的别名引用次数，防止类似 Billion Laughs 的 YAML 别名攻击（见 parser/metadecoders/decoder.go）。

Options 配置详解

transform.Unmarshal接受一个 options map 作为第一个参数，共五个选项，全部定义在 docs/content/en/functions/transform/Unmarshal.md 与源码的Decoder结构体中（parser/metadecoders/decoder.go）：

其中format选项自 Hugo v0.149.0 引入，targetType自 v0.146.7 引入（官方文档标注为 new-in）。format对资源而言仅在文件缺少扩展名或需要覆盖推断结果时才必需；对字符串而言仅当格式存在歧义时才需要显式指定。

源码中的选项解析细节

选项解析在decodeDecoder函数中完成（tpl/transform/unmarshal.go），两个关键细节：

1. delimiter与comment需要转换成rune（单个字符）。由于mapstructure不支持 string 到 rune 的转换（引用了 mitchellh/mapstructure issue #151），源码先手动通过stringToRune处理这两个键，且键名大小写不敏感（DElimiter也能生效，测试用例验证了这一点）。
2. 其余选项（format、lazyQuotes、targetType）通过mapstructure.WeakDecode弱类型解码注入。

CSV 解码的实际执行位于 parser/metadecoders/decoder.go：

• targetType为slice时，返回[][]string，即所有行（含表头）的二维数组；
• targetType为map时，首行作为字段名（表头），其余每行转换为map[string]string，返回[]map[string]string；表头行重复字段名或数据行数不足两行会报错。

实战一：反序列化字符串

字符串输入是最简单的用法。官方文档示例（YAML 格式）：

{{ $string := ` title: Les Misérables author: Victor Hugo `}} {{ $book := transform.Unmarshal $string }} {{ $book.title }} → Les Misérables {{ $book.author }} → Victor Hugo

边界行为

从测试用例（tpl/transform/unmarshal_test.go）可以确认以下边界行为：

• 空字符串或纯空白字符串返回nil, nil，不会报错；
• 同一个字符串可以用 JSON、YAML、TOML 三种写法解析出相同结果（{ "slogan": "Hugo Rocks!" }、slogan: "Hugo Rocks!"、slogan = "Hugo Rocks!"）；
• 无法识别的格式（如"thisisnotavaliddataformat"）返回错误；
• 传入不支持的 Go 类型（如无字符串表示的自定义结构体）返回type %T not supported错误。

实战二：反序列化资源

官方文档指出，transform.Unmarshal可配合全局资源（global）、页面资源（page）和远程资源（remote）使用，并且 Hugo 会对结果进行缓存——对同一资源多次调用不会产生额外开销。

全局资源（assets 目录）

全局资源指assets目录内（或挂载到assets目录的任何目录内）的文件：

assets/ └── data/ └── books.json

{{ $data := dict }} {{ $path := "data/books.json" }} {{ with resources.Get $path }} {{ with . | transform.Unmarshal }} {{ $data = . }} {{ end }} {{ else }} {{ errorf "Unable to get global resource %q" $path }} {{ end }} {{ range where $data "author" "Victor Hugo" }} {{ .title }} → Les Misérables {{ end }}

页面资源（page bundle 内）

页面资源位于 page bundle 目录内，通过.Resources.Get获取：

content/ ├── post/ │ └── book-reviews/ │ ├── books.json │ └── index.md └── _index.md

{{ $data := dict }} {{ $path := "books.json" }} {{ with .Resources.Get $path }} {{ with . | transform.Unmarshal }} {{ $data = . }} {{ end }} {{ else }} {{ errorf "Unable to get page resource %q" $path }} {{ end }}

远程资源（HTTP/HTTPS）

远程资源通过resources.GetRemote获取，官方文档推荐配合try进行错误处理：

{{ $data := dict }} {{ $url := "https://example.org/books.json" }} {{ with try (resources.GetRemote $url) }} {{ with .Err }} {{ errorf "%s" . }} {{ else with .Value }} {{ $data = . | transform.Unmarshal }} {{ else }} {{ errorf "Unable to get remote resource %q" $url }} {{ end }} {{ end }}

[!NOTE] 官方文档特别提醒：当远程服务器返回错误的Content-Type响应头（例如把 JSON 返回为application/octet-stream）时，直接对资源调用transform.Unmarshal会因媒体类型不被支持而失败。此时应改为把资源的Content字符串传给函数：

{{ $data = .Content | transform.Unmarshal }}

这一行为与源码实现吻合——资源分支依赖r.MediaType().Suffixes()推断格式（tpl/transform/unmarshal.go），而字符串分支则走内容推断逻辑。

实战三：处理 CSV 数据

以下示例使用官方文档中的 pets.csv：

"name","type","breed","age" "Spot","dog","Collie",3 "Rover","dog","Boxer",5 "Felix","cat","Calico",7

targetType 为 slice：渲染完整表格

{{ $data := slice }} {{ $file := "pets.csv" }} {{ with or (.Resources.Get $file) (resources.Get $file) }} {{ $opts := dict "targetType" "slice" }} {{ $data = transform.Unmarshal $opts . }} {{ end }} {{ with $data }} <table> <thead> <tr> {{ range index . 0 }} <th>{{ . }}</th> {{ end }} </tr> </thead> <tbody> {{ range . | after 1 }} <tr> {{ range . }} <td>{{ . }}</td> {{ end }} </tr> {{ end }} </tbody> </table> {{ end }}

slice 模式下返回[][]string，第一行是表头，因此用index . 0渲染表头、after 1跳过表头渲染数据行。

targetType 为 map：提取与排序

要提取子集或排序，官方文档推荐改用 map 模式——每行数据带有字段名，可直接用where和sort处理：

{{ $data := dict }} {{ $file := "pets.csv" }} {{ with or (.Resources.Get $file) (resources.Get $file) }} {{ $opts := dict "targetType" "map" }} {{ $data = transform.Unmarshal $opts . }} {{ end }} {{ with sort (where $data "type" "dog") "name" "asc" }} <table> <thead> <tr> <th>name</th> <th>type</th> <th>breed</th> <th>age</th> </tr> </thead> <tbody> {{ range . }} <tr> <td>{{ .name }}</td> <td>{{ .type }}</td> <td>{{ .breed }}</td> <td>{{ .age }}</td> </tr> {{ end }} </tbody> </table> {{ end }}

自定义分隔符与注释行

CSV 不一定是逗号分隔。测试用例（tpl/transform/unmarshal_test.go）验证了自定义分隔符与注释字符的用法：

{{ $opts := dict "delimiter" ";" "comment" "%" }} {{ $data = transform.Unmarshal $opts $resource }}

当 CSV 内容包含以%开头的注释行（如% This is a comment）时，这些行会被自动忽略。注意delimiter与comment只接受单字符，多字符会报invalid character错误。

实战四：处理 XML 数据

根节点剥离规则

官方文档明确：反序列化 XML 时，不要在访问数据时包含根节点。例如对下面这个 RSS feed，访问标题要用$data.channel.title而非$data.rss.channel.title：

<?xml version="1.0" encoding="utf-8" standalone="yes"?> <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"> <channel> <title>Books on Example Site</title> ... <item> <title>The Hunchback of Notre Dame</title> <link>https://example.org/books/the-hunchback-of-notre-dame/</link> </item> <item> <title>Les Misérables</title> <link>https://example.org/books/les-miserables/</link> </item> </channel> </rss>

{{ $data := dict }} {{ $url := "https://example.org/books/index.xml" }} {{ with try (resources.GetRemote $url) }} {{ with .Err }} {{ errorf "%s" . }} {{ else with .Value }} {{ $data = . | transform.Unmarshal }} {{ else }} {{ errorf "Unable to get remote resource %q" $url }} {{ end }} {{ end }} {{ with $data.channel.item }} <ul> {{ range . }} <li>{{ .title }}</li> {{ end }} </ul> {{ end }}

渲染结果为：

<ul> <li>The Hunchback of Notre Dame</li> <li>Les Misérables</li> </ul>

这一行为与源码一致：XML 解码通过mxj库（xml.NewMapXml）进行，随后取出根节点下的 map 作为最终结果（见 parser/metadecoders/decoder.go）。

XML 属性与命名空间

当 XML 节点带属性或命名空间时，数据结构会发生变化。以官方文档中的带lang属性和isbn:number命名空间节点的 RSS 为例，用debug.Dump检查后，每个 item 节点结构如下：

{ "description": "Written by Victor Hugo", "guid": "https://example.org/books/the-hunchback-of-notre-dame/", "link": "https://example.org/books/the-hunchback-of-notre-dame/", "number": "9780140443530", "pubDate": "Mon, 09 Oct 2023 09:27:12 -0700", "title": { "#text": "The Hunchback of Notre Dame", "-lang": "en" } }

要点：

• 命名空间前缀（isbn:）被剥离，isbn:number变成number键；
• 元素文本内容存放在#text键下；
• 属性存放在以-开头的键下（如-lang）。

由于#text、-lang不是合法的 Go 标识符（不以字母或下划线开头），不能用.title点号语法访问，必须借助index函数：

{{ with $data.channel.item }} <ul> {{ range . }} {{ $title := index .title "#text" }} {{ $lang := index .title "-lang" }} {{ $ISBN := .number }} <li>{{ $title }} ({{ $lang }}) {{ $ISBN }}</li> {{ end }} </ul> {{ end }}

渲染结果：

<ul> <li>The Hunchback of Notre Dame (en) 9780140443530</li> <li>Les Misérables (fr) 9780451419439</li> </ul>

底层实现：缓存、键与失效

从源码看，transform.Unmarshal并不是每次调用都重新解析数据，而是走了一个双层设计（tpl/transform/unmarshal.go）：

• 内存分区缓存：命名空间初始化时通过dynacache.GetOrCreatePartition创建/tmpl/transform/unmarshal分区（权重 30，ClearOnChange时清空），见 tpl/transform/init.go。
• 缓存键：
  • 字符串输入：以hashing.XxHashFromStringHexEncoded对原始内容计算的 XXHash 十六进制串为键；若指定了非默认 options，还会拼接OptionsKey()（由 format、delimiter、comment、lazyQuotes、targetType 拼成，见 parser/metadecoders/decoder.go）；
  • 资源输入：以资源Key()为键，同样可拼接 options 键。
• 陈旧版本追踪：缓存值是resources.StaleValue[any]，资源分支通过resource.StaleVersion(r)感知资源内容变化并自动失效，字符串分支的 StaleVersionFunc 恒为 0（字符串内容即缓存键本身，天然不可变）。

此外，命名空间暴露了Reset()方法用于清空 unmarshal 缓存分区（tpl/transform/transform.go），测试用例在每轮迭代前调用它以隔离缓存影响。

对于资源输入还有一个先决条件：资源必须实现resource.UnmarshableResource接口（提供Key()等方法），未设置 Key 的资源会返回no Key set in Resource错误（tpl/transform/unmarshal.go）。

常见错误与排查

汇总官方文档与测试用例中出现的典型错误场景（均可在 tpl/transform/unmarshal_test.go 中找到对应验证）：

实践建议：优先让 Hugo 自动推断格式（字符串按内容、资源按媒体类型后缀），仅在文件无扩展名或格式存在歧义时显式传入format选项；解析远程数据时留意错误的 Content-Type 响应头，必要时改用.Content | transform.Unmarshal的字符串路径。

延伸阅读

• 函数完整官方文档：docs/content/en/functions/transform/Unmarshal.md
• 术语表词条：docs/content/en/quick-reference/glossary/unmarshal.md
• 核心实现：tpl/transform/unmarshal.go
• 模板函数注册与别名：tpl/transform/init.go
• 解码器与格式推断：parser/metadecoders/decoder.go、parser/metadecoders/format.go
• 行为验证测试：tpl/transform/unmarshal_test.go

transform.Unmarshal是 Hugo 模板中连接"外部数据"与"渲染逻辑"的桥梁，无论数据来自站内资源、页面 bundle 还是远程 API，掌握其格式推断规则、options 语义与 XML/CSV 的特殊访问方式，都能让你在模板中安全、高效地消费结构化数据。

• 开发工具
• 前端
• CLI