youtube
用 youtube 短代码在正文中嵌入 YouTube 视频:完整参数表、可复制的调用、实测 iframe 输出、起止秒数与隐私开关。
开始之前,你需要
- 站点能构建成功(
hugo --renderToMemory退出码为 0)。 - 知道自己要嵌入的视频地址,能从中取出 11 位的视频 ID。
读完之后你能
- 写出带
start/end/loading/title的youtube调用; - 在产物里核对
div+iframe结构,以及参数如何变成 URL 查询参数; - 用
[privacy.youTube]的privacyEnhanced切换到youtube-nocookie.com,并说清它挡住了什么。
这一页解决什么问题
直接贴 YouTube 的嵌入代码会得到一长串 iframe 属性:allow、referrerpolicy、按比例撑高的容器、URL 上的 autoplay / start / loop 查询参数。手写容易漏,尤其是「从第 30 秒开始播到第 60 秒」这种需求。
youtube 短代码把这些参数变成短代码参数:你写视频 ID 和 start=30 end=60,Hugo 负责拼出正确的 iframe 与 URL 查询参数。
youtube 短代码在正文中嵌入一个 YouTube 播放器,默认输出带 style 属性的 iframe 元素,外层包一个带 style 属性的 div 元素。
示例
要展示地址为 https://www.youtube.com/watch?v=0RKpf3rK57I 的视频,只需在 Markdown 中写入视频 ID:
{{< youtube 0RKpf3rK57I >}}你应当看到什么(实测输出,Hugo 0.167,为便于对照做了换行):
<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
<iframe
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share; fullscreen"
loading="eager"
referrerpolicy="strict-origin-when-cross-origin"
src="https://www.youtube.com/embed/0RKpf3rK57I?autoplay=0&controls=1&end=0&loop=0&mute=0&start=0"
style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border:0;"
title="YouTube video"></iframe>
</div>三个值得注意的地方:
- 外层
div用padding-bottom: 56.25%(16:9)撑高,iframe绝对定位铺满,因此窄屏不变形; - 参数最终变成 URL 查询参数:
autoplay、controls、end、loop、mute、start都在src上,没有给默认值的参数显示为0或1; title默认是YouTube video——这是无障碍属性,建议按视频内容改成有意义的中文标题。
也可以使用命名参数,并同时指定播放区间与加载方式:
{{< youtube id=0RKpf3rK57I start=30 end=60 loading=lazy >}}实测输出(Hugo 0.167;allow、referrerpolicy、style 与默认一致,只为对照换行):
<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
<iframe
allow="…"
loading="lazy"
referrerpolicy="strict-origin-when-cross-origin"
src="https://www.youtube.com/embed/0RKpf3rK57I?autoplay=0&controls=1&end=60&loop=0&mute=0&start=30"
style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border:0;"
title="YouTube video"></iframe>
</div>把 autoplay、loop、class、title 一起叠上去,就能看清参数之间的连带关系:
{{< youtube id=0RKpf3rK57I start=30 end=60 loading=lazy autoplay=true loop=true class="yt-class" title="yt title" >}}实测输出(同一版本):
<div class="yt-class">
<iframe
allow="…"
loading="lazy"
referrerpolicy="strict-origin-when-cross-origin"
src="https://www.youtube.com/embed/0RKpf3rK57I?autoplay=1&controls=1&end=60&loop=1&mute=1&playlist=0RKpf3rK57I&start=30"
title="yt title"></iframe>
</div>两条链路能对上:autoplay=1 同时带来 mute=1(见参数表),loop=1 让 URL 里多出 playlist=<视频ID>。
本站实际渲染效果
下面两个播放器都是本站构建时由 youtube 短代码生成的 iframe——真实嵌入,不是截图:
上面第二个播放器点了播放后应当从第 30 秒开始,到第 60 秒停止——这就是参数变成 URL 查询参数之后的实际效果。两个 iframe 的 title 也不一样,屏幕阅读器读的就是它。
参数
| 参数名 | 类型 | 说明 |
|---|---|---|
id |
string |
视频的 id。当 id 是第一个且唯一的位置参数时可以省略。 |
allowFullScreen |
bool |
iframe 元素能否激活全屏模式。默认值为 true。 |
autoplay |
bool |
是否自动播放视频。会强制把 mute 设为 true。默认值为 false。 |
class |
string |
外层 div 元素的 class 属性。指定后,会移除 iframe 元素及其外层 div 元素上的 style 属性。 |
controls |
bool |
是否显示视频控件。默认值为 true。 |
end |
int |
播放器停止播放的时间点,以视频开始后的秒数计。 |
loading |
string |
iframe 元素的 loading 属性,取值为 eager 或 lazy。默认值为 eager。 |
loop |
bool |
是否无限重复视频。首次播放之后会忽略 start 与 end 参数。默认值为 false。 |
mute |
bool |
是否静音。当 autoplay 为 true 时始终为 true。默认值为 false。 |
start |
int |
播放器开始播放的时间点,以视频开始后的秒数计。 |
title |
string |
iframe 元素的 title 属性。默认值为 YouTube video。 |
把 loading 设为 lazy 可以推迟视频的加载,减少首屏开销;首屏以内的视频则应保留默认的 eager。
参数之间的相互影响
这几条是实际写作时最容易忽略的:
| 你写了 | 连带发生什么 |
|---|---|
autoplay=true |
mute 被强制为 true(多数浏览器只允许静音自动播放) |
autoplay=true loading="lazy" |
视频要等进入视口才开始加载,自动播放往往在用户已经滚过去之后才发生——两者通常不该同时用 |
loop=true |
首次播放后忽略 start / end;URL 上会多出 playlist=<视频ID>(YouTube 侧要求同视频才能循环) |
class="…" |
div 与 iframe 的 style 被移除,需自带 CSS |
title="…" 不写 |
无障碍标签停在英文的 YouTube video |
视频 ID 从哪来
视频地址通常是下面两种形式,ID 都是 v= 或 youtu.be/ 之后的那 11 位字符:
https://www.youtube.com/watch?v=0RKpf3rK57I
https://youtu.be/0RKpf3rK57I短代码只认 ID,不要把整个地址填进去。
隐私
嵌入第三方内容会向对方发起请求,因此相关行为由项目配置中的隐私设置控制:
[privacy.youTube]
disable = false
privacyEnhanced = false配置键名不区分大小写,写作 [privacy.youtube] 同样有效。
disable- (
bool)是否禁用该短代码。默认值为false。 privacyEnhanced- (
bool)是否阻止 YouTube 在用户播放嵌入视频之前收集网站访客信息。默认值为false。
实测(Hugo 0.167):
| 配置 | 产物里的变化 |
|---|---|
| 默认 | iframe src="https://www.youtube.com/embed/0RKpf3rK57I?…" |
privacyEnhanced = true |
iframe src="https://www.youtube-nocookie.com/embed/0RKpf3rK57I?…"——域名换成无 Cookie 站点 |
disable = true |
短代码什么都不输出,构建不报错、不警告 |
标准模式在构建时不访问 YouTube,上面那套 HTML 是静态拼出来的,断网也能构建。
什么时候用,什么时候别用
该用:
- 正文里真的要看视频,且希望窄屏自适应;
- 需要「从第 30 秒开始、到第 60 秒停」这类区间播放;
- 需要
privacyEnhanced减轻第三方跟踪。
别用:
- 只想给出视频链接 → 直接写 Markdown 链接;
- 页面首屏以外有很多视频、又不想拖慢首屏 → 要么加
loading="lazy",要么改成点击后再加载(那需要自定义短代码); - 需要完全离线可用的产物 → 嵌入本质上依赖第三方域名,离线场景请改用本地视频文件。
验证方法
-
在内容里写一次调用:
content/example.mdmd{{< youtube id=0RKpf3rK57I start=30 end=60 loading=lazy title="产品演示" >}} -
构建:
bashhugo -
打开
public/example/index.html,搜索youtube.com/embed。
你应当看到什么:一个 iframe,loading="lazy",title="产品演示",src 指向 https://www.youtube.com/embed/0RKpf3rK57I,并在问号后面带上 …end=60…start=30 这些查询参数。
src里应当同时有start=30与end=60,说明参数被正确拼进了 URL;- 若
src是youtube-nocookie.com,说明站点开了privacyEnhanced; - 搜不到
youtube.com/embed→ 检查[privacy.youTube] disable是不是true; iframe在、但页面视频区域高度为 0 → 你用了class却没写撑高的 CSS;- 播放、全屏、自动播放这些行为必须在浏览器里验证,构建产物检查不到。
常见坑
| 类别 | 现象 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 加了 class 后视频区域塌陷 |
class 会移除内联样式,而你没写配套 CSS |
自己写 position: relative; padding-bottom: 56.25% 一类样式;或去掉 class |
| 没报错但结果不对 | 自动播放没声音 | autoplay=true 会强制静音,这是浏览器的普遍限制 |
需要声音就别用 autoplay |
| 没报错但结果不对 | loop=true 后 start / end 失效 |
文档明确:首次播放之后忽略这两个参数 | 需要区间循环时自己控制播放器 |
| 没报错但结果不对 | 读屏软件念出英文的「YouTube video」 | 没写 title |
补上有意义的 title |
| 没报错但结果不对 | 产物里完全没有嵌入内容 | [privacy.youTube] disable = true |
改成 false |
| 报错看不懂 | failed to extract shortcode: template for shortcode "youtube" not found |
layouts/_shortcodes/ 下有同名文件但内容有误 |
删掉自定义文件即恢复内置版本 |
更多排查入口见故障排查。