x
用 x 短代码在正文中嵌入 X 帖子:两个必需参数、构建时会联网取数据、隐私与简单模式、失败时的排查表。
开始之前,你需要
- 站点能构建成功(
hugo --renderToMemory退出码为 0),Hugo 版本为 0.141.0 或更高。 - 构建机可以访问外网(本页的默认模式需要联网,见「构建时会联网」)。
读完之后你能
- 从帖子地址拆出
user与id,写出能被构建的调用; - 说清默认模式与简单模式的区别,以及为什么构建会依赖网络;
- 遇到
unable to retrieve the remote data时,按本页排查表定位是网络、权限还是配置问题。
这一页解决什么问题
引用一条 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:
{{< 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 iduser不要带前导@;id是一长串数字,不要加引号以外的任何修饰;- 老地址域名是
twitter.com,用户名与 ID 的取法相同。
隐私
嵌入第三方内容会向对方发起请求,因此相关行为由项目配置中的隐私设置控制:
[privacy.x]
disable = false
enableDNT = false
simple = falsedisable- (
bool)是否禁用该短代码。默认值为false。 enableDNT- (
bool)是否阻止 X 把帖子数据与嵌入页面数据用于个性化推荐和广告。默认值为false。 simple- (
bool)是否启用简单模式。取true时,Hugo 构建出不含 JavaScript 的静态帖子版本。默认值为false。
简单模式版本的短代码源码见这个文件。
启用简单模式后,如果想去掉硬编码的内联样式,可以在项目配置中把 disableInlineCSS 设为 true:
[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;
- 只想引用一句话 → 直接抄文字并给出链接,不引入第三方请求;
- 帖子可能被删除或账号转私密 → 第三方嵌入迟早失效,重要内容请自留副本;
- 需要稳定的产物(同一份源码每次构建输出完全一致)→ 外部接口返回的内容会变,做不到。
验证方法
-
在内容里写一次调用:
md{{< x user="SanDiegoZoo" id="1453110110599868418" >}} -
构建,同时留意日志:
bashhugo -
打开
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;删掉自定义文件即恢复内置版本 |
更多排查入口见故障排查。