Hugo 博客写作指南（五）：YAML 和 TOML 中的引号使用规则

2026-03-04 6 分钟 2785 字
技术教程 Hugo YAML TOML 配置 写作指南
Hugo 博客写作指南（五）：YAML 和 TOML 中的引号使用规则

Hugo 博客写作指南（五）：YAML 和 TOML 中的引号使用规则

本文是 Hugo 博客写作指南系列的第五篇，详细说明 YAML 和 TOML 配置文件中引号的正确使用规则。

在 Hugo 博客写作中，我们会接触到两种配置文件格式：

  • YAML - 用于 Front Matter（文章开头的元数据）
  • TOML - 用于 hugo.toml（站点配置文件）

正确使用引号对于避免解析错误非常重要。

一、YAML 中的引号规则（Front Matter）

1. 什么时候可以不用引号？

简单字符串可以不用引号：

# ✅ 正确 - 简单字符串
title: 我的博客
description: 记录生活分享知识
author: 长安

但是，以下情况必须用引号：

2. 必须使用引号的情况

包含特殊字符

# ❌ 错误 - 包含冒号
title: Hugo 教程：第一章

# ✅ 正确 - 用引号包裹
title: "Hugo 教程：第一章"
title: 'Hugo 教程：第一章'

包含方括号或花括号

# ❌ 错误 - 包含方括号
title: 数组 [1, 2, 3]

# ✅ 正确
title: "数组 [1, 2, 3]"

包含井号（注释符号）

# ❌ 错误 - 井号会被识别为注释
title: C# 编程语言

# ✅ 正确
title: "C# 编程语言"

包含引号本身

# ✅ 正确 - 转义内部引号
quote: "他说：\"你好\""
quote: '他说："你好"'

以空格开头或结尾

# ✅ 正确 - 保留空格
title: "  前面有空格  "

包含 YAML 关键字

# ❌ 错误 - true 会被识别为布尔值
enabled: true

# ✅ 正确 - 作为字符串
enabled: "true"

包含中文标点

虽然中文标点通常不会导致解析错误，但为了统一和避免潜在问题：

# ✅ 推荐 - 统一使用引号
title: "Hugo 博客写作指南（一）：Front Matter 详解"
description: "记录生活，分享知识"

3. 单引号 vs 双引号

YAML 中单引号和双引号的区别：

特性单引号 '双引号 "
转义字符不支持支持（\n, \t, \" 等）
性能略快略慢
推荐场景纯文本需要转义时

示例：

# 单引号 - 原样输出
text: 'Hello\nWorld'  # 输出：Hello\nWorld

# 双引号 - 处理转义
text: "Hello\nWorld"  # 输出：Hello（换行）World

# 包含双引号时使用单引号
quote: '他说："你好"'  # 更简洁

# 包含单引号时使用双引号
quote: "It's a blog"

4. Front Matter 最佳实践

推荐统一使用英文双引号：

---
title: "Hugo 博客写作指南（一）：Front Matter 详解"
date: 2026-03-04
lastmod: 2026-03-04
draft: false
description: "详细介绍 Front Matter 的基本属性和使用方法"
tags: ["Hugo", "博客", "写作指南"]
categories: ["技术教程"]
cover: "/images/default-cover.svg"
star: false
---

为什么推荐双引号？

  1. ✅ 统一风格，易于维护
  2. ✅ 支持转义字符（如需要）
  3. ✅ 避免特殊字符解析问题
  4. ✅ 与 JSON 格式兼容

二、TOML 中的引号规则（hugo.toml）

1. TOML 字符串类型

TOML 支持两种字符串：

基本字符串（使用双引号）

# ✅ 正确 - 双引号
title = "我的博客"
description = "记录生活，分享知识"

支持转义字符：

text = "Hello\nWorld"  # 换行
text = "Tab\there"     # 制表符
text = "Quote: \"Hi\"" # 引号

字面量字符串（使用单引号）

# ✅ 正确 - 单引号
title = '我的博客'
description = '记录生活，分享知识'

不支持转义，原样输出：

text = 'Hello\nWorld'  # 输出：Hello\nWorld（字面意思）
path = 'C:\Users\Name' # 输出：C:\Users\Name

2. 必须使用引号的情况

所有字符串值都必须使用引号：

# ❌ 错误 - 没有引号
title = 我的博客

# ✅ 正确
title = "我的博客"
title = '我的博客'

3. 单引号 vs 双引号

特性单引号 '双引号 "
转义字符不支持支持
反斜杠原样输出转义字符
推荐场景文件路径、正则表达式普通字符串

示例对比：

# 文件路径 - 推荐单引号
path = 'C:\Users\Name\file.txt'
path = '/home/user/file.txt'

# 普通字符串 - 推荐双引号
title = "我的博客"
description = "记录生活，分享知识"

# 包含引号
quote = '他说："你好"'  # 单引号包裹双引号
quote = "It's a blog"   # 双引号包裹单引号

4. hugo.toml 最佳实践

推荐：统一使用单引号

baseURL = 'https://example.com/'
languageCode = 'zh-cn'
title = '我的个人博客'
theme = 'changan'

[params]
  description = '记录生活，分享知识'
  author = '长安'
  motto = '学无止境'
  avatar = '/images/avatar.webp'
  
  [[params.socials]]
    name = 'Github'
    icon = 'icon-github'
    url = 'https://github.com/yourname'

为什么推荐单引号？

  1. ✅ 更简洁，无需转义
  2. ✅ 适合文件路径（Windows 路径）
  3. ✅ 避免反斜杠问题
  4. ✅ TOML 社区推荐做法

例外情况 - 需要转义时使用双引号：

# 包含换行符
text = "第一行\n第二行"

# 包含制表符
code = "Column1\tColumn2"

三、常见错误示例

错误 1：混用引号

# ❌ 错误 - YAML 中使用中文引号
title: "我的博客"
description: "记录生活"

# ✅ 正确 - 使用英文引号
title: "我的博客"
description: "记录生活"

错误 2：TOML 中缺少引号

# ❌ 错误
title = 我的博客

# ✅ 正确
title = "我的博客"

错误 3：YAML 中特殊字符未包裹

# ❌ 错误 - 冒号导致解析错误
title: Hugo 教程：第一章

# ✅ 正确
title: "Hugo 教程：第一章"

错误 4：引号不匹配

# ❌ 错误 - 引号不匹配
title: "我的博客'

# ✅ 正确
title: "我的博客"

错误 5：TOML 中错误使用反引号

# ❌ 错误 - 使用反引号
title = `我的博客`

# ✅ 正确
title = "我的博客"

四、快速参考表

YAML（Front Matter）

场景推荐示例
简单字符串可不用引号title: 博客
包含特殊字符英文双引号title: "教程：第一章"
包含中文英文双引号title: "中文标题"
列表项英文双引号tags: ["Hugo", "博客"]
需要转义英文双引号text: "Hello\nWorld"

TOML（hugo.toml）

场景推荐示例
普通字符串单引号title = '博客'
文件路径单引号path = 'C:\file.txt'
需要转义双引号text = "Hello\nWorld"
包含单引号双引号text = "It's blog"
包含双引号单引号text = '他说："你好"'

五、验证你的配置

使用 Hugo 命令验证

# 查看配置是否有效
hugo config

# 构建站点（会检查配置）
hugo --gc --minify

# 本地预览
hugo server -D

在线验证工具

常见错误排查

错误信息： failed to unmarshal YAML

可能原因：

  1. 使用了中文引号
  2. 引号不匹配
  3. 特殊字符未包裹
  4. 缩进错误

解决方法：

  1. 检查所有引号是否为英文
  2. 确保引号成对出现
  3. 特殊字符用引号包裹
  4. 检查 YAML 缩进（使用空格，不用 Tab）

六、总结

YAML（Front Matter）最佳实践

---
# ✅ 推荐写法
title: "文章标题"
description: "文章描述"
tags: ["标签 1", "标签 2"]
categories: ["分类"]
---

要点：

  • ✅ 统一使用英文双引号
  • ✅ 特殊字符必须包裹
  • ✅ 列表项使用双引号
  • ❌ 不要使用中文引号

TOML（hugo.toml）最佳实践

# ✅ 推荐写法
baseURL = 'https://example.com/'
title = '我的博客'
author = '长安'

# 需要转义时使用双引号
description = "第一行\n第二行"

要点：

  • ✅ 优先使用单引号
  • ✅ 路径使用单引号
  • ✅ 需要转义时用双引号
  • ❌ 所有字符串必须用引号包裹

相关资源

上一篇： Hugo 博客写作指南（四）：ChangAn 主题特色

系列文章：

版权声明

本文作者：长安

本文链接：https://changan.icecome.com/posts/hugo-writing-guide-05-yaml-toml-quotes/