视频插入功能说明

本站通过自研的 {% video %} 标签在文章和万花筒(碎碎念)页面插入视频。本文档介绍该功能的完整明细:支持的平台、链接格式、嵌入方式、通用行为,以及相关文件位置。

一、基本用法

在文章(Markdown)中:

已复制
{% video https://www.bilibili.com/video/BV1P18y6jEkV %}

支持”标题 + 链接”的格式(微信/B站 App 复制出来的带标题链接可直接粘贴,标签会自动忽略标题只取链接):

已复制
{% video 【当大肥鱼吃完你的token后……-哔哩哔哩】 https://b23.tv/PyOivuf %}

协议相对链接也可以(https: 前缀可省略):

已复制
{% video //www.huya.com/video/play/1117994220.html %}

二、平台支持明细

平台 支持的链接形式 嵌入方式
哔哩哔哩 BV 号链接(可带任意参数、可带标题)、b23.tv 手机短链、官方分享嵌入链接(player.bilibili.com) B站官方播放器 iframe。BV 链接构建时调 B站开放接口取 aid/cid,按官方”分享-嵌入代码”同款 isOutside=true 形式生成(外链风控概率更低),接口失败自动回退;直接粘贴的 player.bilibili.com 链接原样使用,但强制关闭自动播放(自动补 autoplay=0&danmaku=0)
AcFun www.acfun.cn/v/acXXX、手机端 m.acfun.cn/v/?ac=XXX AcFun 官方播放器 iframe
虎牙 直播间 huya.com/房间号、手机短链 hy.fan/xxx、已有嵌入链 liveshare.huya.com/iframe/x、录像 huya.com/video/play/ID.html、VOD 链接 点击加载占位卡(见下文)
YouTube youtu.be/ID、youtube.com/watch?v=ID、Shorts 短视频链接 YouTube(nocookie)播放器 iframe
Twitter / X x.com/用户/status/ID(可带 /video/1 等后缀与分享参数) 官方 blockquote 富卡片(widgets.js 自适应高度)
TikTok tiktok.com/@用户/video/ID 官方 blockquote 富卡片(embed.js)
Instagram instagram.com/reel/ID、/p/ID、/tv/ID(手机端 /reels/ 也支持) 官方 blockquote 富卡片(embed.js)
Facebook 仅完整链接:facebook.com/reel/ID、facebook.com/主页/videos/ID、watch?v=ID 官方 fb-video 富卡片(Facebook SDK)
Twitch 直播 twitch.tv/频道、录像 /videos/ID、手机录像 /v/ID Twitch 官方播放器 iframe
Vimeo vimeo.com/数字ID Vimeo 官方播放器 iframe
Niconico nicovideo.jp/watch/smXXXX(soXXXX 同理) 官方嵌入 iframe

明确不支持的形式

形式 生成时的表现
Facebook 分享短链 facebook.com/share/r/xxx、fb.watch/xxx 显示红色提示”不支持 Facebook 分享短链,请粘贴完整链接”(不联网解析)
B站直播 live.bilibili.com、AcFun 直播 live.acfun.cn 显示”不支持的视频链接”(两家均无公开嵌入播放器)
无法识别的链接 显示”不支持的视频链接”,建议直接粘贴平台嵌入代码

关于 YouTube 短视频(Shorts)

youtube.com/shorts/ID 会被自动转换为普通 YouTube 视频嵌入,使用统一的 16:9 响应式容器。竖屏画面由 YouTube 播放器自行加黑边显示,任何情况下不会拉伸变形。不存在单独的”竖屏样式”。

关于富卡片弱网占位

TikTok / Instagram / Twitter / Facebook 的富卡片在平台脚本加载完成前会显示轻量的占位引言(仅一行链接)。占位样式不设最小宽度,窄屏(手机)下始终跟随文章容器宽度,不会把版面撑出横向滚动。

三、通用行为

  1. 不自动播放:所有平台嵌入均显式关闭自动播放(YouTube/Vimeo/Twitch/B站 均带 autoplay=0 类参数,Facebook 卡片 data-autoplay="false")。

  2. 虎牙点击加载占位卡:虎牙播放器无法通过参数关闭自动播放,因此直播与录像一律渲染为黑色占位卡(播放按钮 + “点击加载 · 不自动播放”),由前端脚本 js/video-embed.js 在访客点击后才插入 iframe。

  3. 占位卡”单播放”效果:点开任一视频时,页面上其它已展开的占位卡会自动收回到封面(对虎牙直播即断开直播流,等效暂停)。其余平台(YouTube/B站等)的播放器位于跨域 iframe 内部,网页没有可靠的控制接口,不做强制暂停。

  4. 统一容器样式:16:9 响应式、圆角 8px、阴影、水平居中;宽度随内容列自适应,任何屏幕不发生形变。TikTok 固定 325px、Instagram/Facebook 富卡片最大 540px、Twitter 最大 500px。

  5. pjax 兼容:所有交互脚本基于事件委托并挂全局,主题无感刷新(万花筒/文章页)后功能自动生效;blockquote 富卡片的平台脚本在 pjax 换页后会自动重新处理新内容。

  6. 构建期短链解析(仅国内):b23.tv 与 hy.fan 在构建时直连跟随跳转解析为完整链接,失败时文章中显示红色提示”短链解析失败”,不影响其它内容生成。

  7. **【重要】**Twitch 要求必须指定 parent 参数为你的博客域名,所以本地localhost无法预览会被twitch拒绝访问

    只有部署之后才能查看

四、万花筒(碎碎念)页面使用

数据文件:source/_data/murmur.yml,在条目中加 video 字段即可:

YAML已复制
- date: "2025-6-1"
  content: "分享一个视频"
  video: "https://www.bilibili.com/video/BV12b4y147DE"

支持的平台与文章基本一致(同一套解析规则)。两点差异:

  • 万花筒渲染为同步模板,b23.tv、hy.fan 短链不做构建期跳转解析,请直接填写完整链接;Facebook 分享短链同样不支持(会显示提示);
  • B站链接在万花筒同样会构建时调开放接口生成官方 isOutside 形式播放器(与文章一致);也可以直接粘贴 player.bilibili.com 官方分享链接(会强制关闭自动播放)。

五、错误提示对照

提示 原因 处理办法
[短链解析失败: 链接] b23.tv / hy.fan 构建时跳转失败(断网或链接失效) 换成完整视频链接
[不支持 Facebook 分享短链: 链接] 使用了 share/fb.watch 短链(设计上不支持) 打开短链取地址栏里的完整链接粘贴
[不支持的视频链接: 链接] 平台或链接格式不在支持列表 换支持的格式,或直接粘贴平台嵌入代码

六、相关文件

文件 作用
themes/magzine/scripts/tag/video.js {% video %} 标签核心:平台识别、短链解析、嵌入 HTML 生成
themes/magzine/scripts/other/murmur-video.js 万花筒页面的同步版解析 helper(parse_murmur_video)
themes/magzine/scripts/other/nunjucks-regex-token-fix.js 词法补丁:修复链接中含 r/ 时被 nunjucks 误判为正则导致 URL 变 [object Object] 的问题
themes/magzine/source/js/video-embed.js 前端交互:虎牙占位卡点击加载、占位卡单播放收回
themes/magzine/layout/murmur.pug 万花筒视频渲染模板
themes/magzine/source/css/main.css 富卡片 blockquote 样式重置、占位卡样式
themes/magzine/source/css/murmur.css 万花筒视频容器样式