梦行志手把手教程：怎么让 Hugo shortcode 只显示代码，而不是被直接解析执行
一篇写给踩过坑的人，也写给正在卡住的你的 Hugo LoveIt 实战教程
有些坑，第一次踩进去的时候，真的会让人怀疑人生。😅
明明只是想在文章里展示一段 Hugo shortcode 源码，结果一保存、一刷新，代码没显示出来，页面反而把它执行了，图片也真的渲染出来了。那一刻你会很懵：我不是已经放进代码块了吗，为什么它还是不听话？
后来我才真正搞明白：这类问题最怕的，不是不会写，而是以为“代码块已经足够安全”。实际上，在 Hugo 这里，光有代码块还不够。你还得避免让正文里出现会被 Hugo 识别成真实 shortcode 的原始写法。
这次我干脆把最稳、最不容易再炸构建的方法整理成一篇能直接照着做的版本。它不是“理论上可行”，而是专门冲着“别再报错了”去的。🛠️
一、问题到底出在哪？ 🤔
你本来想展示的是这样一段 shortcode：
注意这里我把原本的 {{ 和 }}，替换成了的 【【 和 】】代替，否则无法构建成功。
这就是我们要解决的问题。
[[< style ".rounded-img img { border-radius: 8px; }" >]]
[[< image src="/images/post-end/night-rain-lamp-1200.webp"
alt="文尾配图水墨画图片"
src_s="/images/post-end/night-rain-lamp-800.webp"
src_l="/images/post-end/night-rain-lamp-1600.webp"
width="100%"
class="rounded-img" >]]
[[< /style >]]但只要这段原始 shortcode 真的出现在文章正文里，Hugo 就有机会先把它当成要执行的东西去解析，而不是当成普通文字展示出来。
一旦它开始解析，像 .rounded-img img { border-radius: 8px; } 这种带点号和 CSS 内容的参数，就很容易触发你看到的那种报错：
unrecognized character in shortcode action: U+002E '.'所以，真正的问题不是“你不会写代码块”，而是文章里仍然出现了 Hugo 眼中的原始 shortcode 语法。⚠️
二、这次我给你的，是绝对更稳的写法 ✅
为了彻底避开构建报错，这篇文章里我不再直接放原始的 shortcode 语法，也不依赖 Hugo 自己的 shortcode 转义机制来赌环境差异。
我给你的方案是：
- 文章里展示时，用“占位符写法”显示源码；
- 读者复制后，再手动替换回真正的
｛｛< ... >｝｝； - 这样 Hugo 在构建时根本看不到可执行 shortcode，自然也就不会再炸。🧯
换句话说，这不是最“优雅”的教程展示法，但它是当前最“稳”的发布法。
三、最安全的展示方式：用占位符代替大括号 ✍️
下面这段，就是我建议你在文章里直接展示给读者看的版本：
```markdown
【【< style ".rounded-img img { border-radius: 8px; }" >】】
【【< image src="/images/post-end/night-rain-lamp-1200.webp"
alt="文尾配图水墨画图片"
src_s="/images/post-end/night-rain-lamp-800.webp"
src_l="/images/post-end/night-rain-lamp-1600.webp"
width="100%"
class="rounded-img" >】】
【【< /style >】】
```这里我把原本的 {{ 和 }}，替换成了更安全的 【【 和 】】。这样做的好处非常直接：
- Hugo 不会把它识别成 shortcode；
- 页面能正常显示代码；
- 读者也能一眼看懂该替换哪里；
- 最重要的是，构建更稳，不容易再冒出奇怪报错。🙂
四、读者复制后怎么恢复成真正可执行代码？ 🔧
你可以在代码块下面直接补一句说明：
使用时，把所有
【【替换成“双左花括号”，再把所有】】替换成“双右花括号”，就能恢复成真正可执行的 Hugo shortcode。
也就是说，上面那段占位符代码，恢复后就是：
【【< style ".rounded-img img { border-radius: 8px; }" >】】
【【< image src="/images/post-end/night-rain-lamp-1200.webp"
alt="文尾配图水墨画图片"
src_s="/images/post-end/night-rain-lamp-800.webp"
src_l="/images/post-end/night-rain-lamp-1600.webp"
width="100%"
class="rounded-img" >】】
【【< /style >】】注意：上面这一段只是说明效果，所以我放在普通文本代码块里；你不要再把它原样塞回文章正文里展示，否则又会回到老问题。😅
五、为什么我这次不继续让你用 shortcode 转义写法？ 🌧️
理论上，Hugo 的确支持用转义方式来展示 shortcode 源码。
关于用 Hugo 的 shortcode 转义写法：
也就是在 shortcode 定界符里加 /* 和 */，这样它就会显示成代码，而不会被执行。
核心规则是：把原来的 {删这字{< … >}} 改成 {删这字{</* … />}}，闭合标签 {删这字{< /style >}} 也同样改成 {删这字{</ /style */>}}。
这是 Hugo 官方社区和相关文档里推荐的 shortcode 转义方式，专门用来在 Markdown 里展示 shortcode 源码示例。
{{< style ".rounded-img img { border-radius: 8px; }" >}}
{{< image src="/images/post-end/night-rain-lamp-1200.webp"
alt="文尾配图水墨画图片"
src_s="/images/post-end/night-rain-lamp-800.webp"
src_l="/images/post-end/night-rain-lamp-1600.webp"
width="100%"
class="rounded-img" >}}
{{< /style >}}如果你只是单行 shortcode，也同样这样处理，例如：
{{< image src="/images/post-end/night-rain-lamp-1200.webp" alt="文尾配图水墨画图片" width="100%" >}}之前明明放在代码块里却还是被解析，是因为 Hugo 在某些 Markdown 渲染场景下，即使在 fenced code block 里也可能继续处理 shortcode，所以只靠三个反引号并不总是够用。
最稳妥的办法就是：代码块 + shortcode 转义 一起用。
但这次你的实际情况已经说明了一件事：你现在更需要的是能稳定构建成功的文件，而不是继续赌不同环境下的解析细节。
尤其当文章里同时出现：
- Markdown 代码块；
- 多行 shortcode；
- 带引号的字符串参数；
- 带点号和花括号的 CSS 片段；
这时候，最保险的办法就是直接绕开 Hugo 对 shortcode 语法的识别入口。占位符法虽然笨一点，但稳。对博客发布来说，稳往往比“看起来更高级”更重要。🕯️
六、手把手操作：你现在到底该怎么写？ 🛠️
如果你想以后每次写 Hugo 教程都不再被这个问题折腾，可以直接按这个流程走。
第一步：把你想展示的原始 shortcode 先写出来
例如原始代码是：
{删这字{< image src="/images/demo.webp" alt="示例图片" width="100%" >}}第二步：把外层大括号换成占位符
改成：
【【< image src="/images/demo.webp" alt="示例图片" width="100%" >】】第三步：再放进 Markdown 代码块里展示
```markdown
【【< image src="/images/demo.webp" alt="示例图片" width="100%" >】】
```第四步：在代码块下面补一句使用说明
比如：
复制后，把
【【改成双左花括号，把】】改成双右花括号，再粘贴到正文里执行。
到这里，这篇教程就既能正常显示，又不容易再把站点构建搞炸。
七、你的这段代码，我帮你改成最终可展示版 📌
你这次最开始那段代码，最终适合放在文章里的版本，我再完整给你放一次：
```markdown
【【< style ".rounded-img img { border-radius: 8px; }" >】】
【【< image src="/images/post-end/night-rain-lamp-1200.webp"
alt="文尾配图水墨画图片"
src_s="/images/post-end/night-rain-lamp-800.webp"
src_l="/images/post-end/night-rain-lamp-1600.webp"
width="100%"
class="rounded-img" >】】
【【< /style >】】
```下面再加一句：
真正使用时，请把
【【改回{{，把】】改回}}。
这样就够了。不要再在同一篇文章里额外放一段真的 ｛｛< style ... >｝｝ 当“实际使用版”，不然很容易再次触发解析。🚫
八、如果是单行 shortcode，也完全一样 ✨
比如你只想展示这一行：
｛｛< image src="/images/post-end/night-rain-lamp-1200.webp" alt="文尾配图水墨画图片" width="100%" >｝｝那文章里安全展示版就写成：
```markdown
【【< image src="/images/post-end/night-rain-lamp-1200.webp" alt="文尾配图水墨画图片" width="100%" >】】
```规则完全一样，不需要另学一套。
九、写在最后 🌌
我越来越觉得，很多技术问题最折磨人的地方，不是它有多难，而是它总把人困在那种“明明快对了，为什么又错了”的来回拉扯里。
你改一遍，刷一遍，再改一遍，再刷一遍。最后消耗掉的往往不只是时间，还有注意力、耐心，以及那一点原本不该浪费的心气。
所以这次我不再给你“理论上更优雅但环境里未必最稳”的版本，而是直接给你一份更适合发出去、也更不容易报错的发布版。它可能不炫，但足够可靠。
如果这篇文章刚好帮你少掉一次无效折腾，那它就已经值了。🤝
–全文完–
“同频之人，终会相遇；同行之路，终有光亮。”
“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”
本文采用 CC BY-NC-SA 4.0 许可协议，转载请注明来自https://oklife.me。
