短代码

x

用 x 短代码在正文中嵌入 X 帖子:两个必需参数、构建时会联网取数据、隐私与简单模式、失败时的排查表。

难度
进阶
预计用时
10 分钟

开始之前,你需要

  • 站点能构建成功(hugo --renderToMemory 退出码为 0),Hugo 版本为 0.141.0 或更高。
  • 构建机可以访问外网(本页的默认模式需要联网,见「构建时会联网」)。

读完之后你能

  • 从帖子地址拆出 user 与 id,写出能被构建的调用;
  • 说清默认模式与简单模式的区别,以及为什么构建会依赖网络;
  • 遇到 unable to retrieve the remote data 时,按本页排查表定位是网络、权限还是配置问题。

接着读:instagram · vimeo

这一页解决什么问题

引用一条 X(原 Twitter)帖子,通常要贴它的嵌入代码或用官方 widget 脚本。x 短代码把这件事简化成两个参数:作者用户名与帖子 ID。

有一点必须在动手前知道:这个短代码在构建时会向外请求 oEmbed 数据。它是本节 11 个内置短代码里少数几个让构建依赖网络的一个,因此「构建机能不能出网」会直接决定它是否渲染成功。自 Hugo 0.141.0 起可用。

x 短代码在正文中嵌入一条 X(原 Twitter)帖子。自 Hugo 0.141.0 起可用。

示例

要展示地址为 https://x.com/SanDiegoZoo/status/1453110110599868418 的帖子,需要给出作者用户名与帖子 ID:

content/example.mdmd
{{< x user="SanDiegoZoo" id="1453110110599868418" >}}

你应当看到什么:构建成功后,产物 public/example/index.html 里出现一段源自 X oEmbed 的 HTML(典型形态是 blockquote.twitter-tweet)。这段 HTML 由 X 的接口返回,标签与文字都可能随帖子变化,不要照抄本文的示例文字。

实测(Hugo 0.167,对照二进制内嵌模板 _shortcodes/x.html):默认模式只把 oEmbed 返回的 html 字段原样输出,不会额外插入内联样式;那段带左侧蓝边的 <style>(.twitter-tweet { border-left: 4px solid #2b7bb9; … })只在简单模式(simple = true)下由 x_simple.html 输出,并可用 [services.x] disableInlineCSS 关掉。

构建时会联网

实测(Hugo 0.167):x 短代码在构建时通过 resources.GetRemote 请求

https://publish.x.com/oembed?dnt=false&url=https%3A%2F%2Fx.com%2FSanDiegoZoo%2Fstatus%2F1453110110599868418

请求的 URL 随配置变化(三种都实测于 Hugo 0.167):

配置 请求的 URL
默认 …/oembed?dnt=false&url=…
[privacy.x] enableDNT = true …/oembed?dnt=true&url=…
[privacy.x] simple = true …/oembed?dnt=false&omit_script=true&url=…(简单模式多一个 omit_script=true)

拿不到数据时,Hugo 只打印一条 WARNING,不中断构建,该位置输出空内容:

WARN  The "x" shortcode was unable to retrieve the remote data: … error calling GetRemote: … See "content/example.md:7:1"

本站为什么没有放「实际渲染效果」

本章其余各页都放了真实调用,这一页是唯一的例外,原因正是本节自己写的那一条:x 短代码在构建时要向 publish.x.com 请求 oEmbed 数据。

本站的构建契约是「不依赖网络、断网也能构建」。一旦正文里出现真实的 {{< x … >}} 调用,两件事会同时发生:

  • 构建时多一次外部请求(结果会缓存进 resources/);
  • 拿不到数据时只打印 WARNING,该位置输出空内容——而本站的严格构建带 --panicOnWarning,这条警告会直接把构建判为失败。

实测(Hugo 0.167.0,Windows,最小站点):放一个真实调用后,普通构建 hugo 退出码为 0,日志里出现

WARN  The "x" shortcode was unable to retrieve the remote data: … error calling GetRemote: … See "content/example.md:7:1"

同一条命令加上 --panicOnWarning 后退出码变为 2。所以在「必须断网可构建」的站点里,这个短代码只适合放进单独允许联网的构建,或者改用「纯链接 + 官方嵌入代码」的静态写法。

想在自己站点上看真实产物:放一个调用,执行 hugo --ignoreCache,然后到 public/ 里按内容文件的路径打开 index.html——有网时那里是一段来自 oEmbed 的 blockquote.twitter-tweet;无网时那一处什么都没有,只有日志里那行警告。

参数

参数名 类型 说明
user string 帖子作者的 X 用户名,即帖子地址中 x.com/ 之后、/status/ 之前的部分。
id string 帖子的 ID,即帖子地址中 /status/ 之后的部分。

两个参数都使用命名参数写法传入,值需加引号。

怎么拆地址

以 https://x.com/SanDiegoZoo/status/1453110110599868418 为例:

https://x.com/SanDiegoZoo/status/1453110110599868418
                └────┬────┘        └────────┬────────┘
                   user                   id
  • user 不要带前导 @;
  • id 是一长串数字,不要加引号以外的任何修饰;
  • 老地址域名是 twitter.com,用户名与 ID 的取法相同。

隐私

嵌入第三方内容会向对方发起请求,因此相关行为由项目配置中的隐私设置控制:

toml
[privacy.x]
disable = false
enableDNT = false
simple = false
disable
(bool)是否禁用该短代码。默认值为 false。
enableDNT
(bool)是否阻止 X 把帖子数据与嵌入页面数据用于个性化推荐和广告。默认值为 false。
simple
(bool)是否启用简单模式。取 true 时,Hugo 构建出不含 JavaScript 的静态帖子版本。默认值为 false。

简单模式版本的短代码源码见这个文件。

启用简单模式后,如果想去掉硬编码的内联样式,可以在项目配置中把 disableInlineCSS 设为 true:

toml
[services.x]
disableInlineCSS = false

该设置默认值为 false。

实测(Hugo 0.167):

配置 产物里的变化
默认 请求 …/oembed?dnt=false&url=…,把 oEmbed 返回的 html 原样输出,不附加内联样式
enableDNT = true 请求参数变成 dnt=true(产物本身不变)
simple = true 请求 …/oembed?dnt=false&omit_script=true&url=…,输出不含 JavaScript 的静态版本,并由 x_simple.html 插入一段内联 <style>;该模板会读取 services.x.disableInlineCSS,为 true 时不输出这段样式
disable = true 短代码什么都不输出,构建不报错、不警告

两种模式都要联网:简单模式省掉的是访客浏览器加载 X 脚本,不是构建时的请求。因此断网环境里这个短代码无法使用(会出现上面的 WARNING 与空输出)。

什么时候用,什么时候别用

该用:

  • 内容确实以某条 X 帖子为主题,且你接受构建依赖外网;
  • 站点有隐私要求 → 至少设 enableDNT = true;不想让访客加载 X 脚本 → 用 simple = true。

别用:

  • 构建环境不能出网(内网 CI、离线打包)→ 这个短代码会静默输出空内容,改用截图 + figure;
  • 只想引用一句话 → 直接抄文字并给出链接,不引入第三方请求;
  • 帖子可能被删除或账号转私密 → 第三方嵌入迟早失效,重要内容请自留副本;
  • 需要稳定的产物(同一份源码每次构建输出完全一致)→ 外部接口返回的内容会变,做不到。

验证方法

  1. 在内容里写一次调用:

    md
    {{< x user="SanDiegoZoo" id="1453110110599868418" >}}
  2. 构建,同时留意日志:

    bash
    hugo
  3. 打开 public/example/index.html,搜索 twitter-tweet 或帖子 ID。

你应当看到什么:

  • 成功:产物里有 blockquote.twitter-tweet 与指向 https://x.com/…/status/1453110110599868418 的链接;
  • 失败(最常见):产物里该位置为空,构建日志里出现 The "x" shortcode was unable to retrieve the remote data。

排查顺序建议是:先看日志有没有 WARNING → 再用浏览器直接打开那个 oEmbed 地址看能不能访问 → 最后才怀疑参数。

常见坑

类别 现象 真因 怎么修
没报错但结果不对 构建成功,页面上什么都没有 构建机访问不到 publish.x.com,短代码只发 WARNING 并输出空内容 看构建日志确认;给构建环境放行网络,或改用截图
没报错但结果不对 产物里完全没有内容,且日志干净 [privacy.x] disable = true 改成 false
没报错但结果不对 帖子结构与样式都变了 oEmbed 返回的 HTML 由 X 决定,不受 Hugo 控制 接受它,或改用 simple + disableInlineCSS 自行控制样式
报错看不懂 unable to retrieve the remote data 网络不可达、代理未配置、或构建环境有出网限制 先解决网络;CI 环境可考虑把结果缓存或改用静态替代方案
没报错但结果不对 页面上直接显示了短代码的调用原文 把文档里的转义写法抄进了正文 删掉 /* 与 */
报错看不懂 failed to extract shortcode: template for shortcode "x" not found Hugo 版本低于 0.141.0,或 layouts/_shortcodes/ 下的自定义文件有误 升级 Hugo;删掉自定义文件即恢复内置版本

更多排查入口见故障排查。