写文章或发瞬间时，经常想顺手放一段视频。直接贴一个 B 站链接显得生硬，用截图又没法播放。于是本站新增了「视频卡片」：在文章里写一行指令，填 B 站的 BV 号就会自动抓取标题、UP主、时长与封面，渲染成一张主题风格的卡片，点击封面就能在站内展开 B 站官方播放器；填 mp4 直链则渲染成带自定义控制条的站内播放器。
下面用几个例子演示它的用法，也是这篇文章本身的真实渲染效果。
语法
视频卡片由 ::video 指令构成，必须独立成段书写，src 与 id 二选一：
::video{id=BV号或B站链接}
::video{src=mp4直链 poster=封面 ratio=9/16}id填 B 站的 BV 号、av 号、视频页链接或 b23.tv 短链，构建期自动抓取视频信息。src填 mp4 直链（public/下的本地路径或第三方直链），走站内自绘播放器。- 两者同时填写时
src优先；poster、title等显式属性永远优先于自动抓取的结果。
嵌入 B 站视频
最常见的情况，只填一个 BV 号。构建时插件会请求 B 站的公开接口，取出标题、UP主、时长与封面；卡片默认只显示封面，点击居中的播放键才会加载 B 站官方外链播放器，之后清晰度、弹幕、全屏都交给官方播放器自己控制：
不想找 BV 号，直接把视频页链接贴进去也可以，短链 b23.tv 同样支持（构建期自动跟随跳转解析）：
mp4 直链播放器
src 指向 mp4 文件时（本地放 public/video/ 下按路径引用，或任何稳定直链），渲染为自定义控制条的站内播放器。提供了 poster 时首屏零字节；未提供封面时只预载几 KB 的元数据并显示视频首帧，不会是一片黑。竖屏视频可以用 ratio 指定宽高比，比如 ratio=9/16：
在 MDX 里用组件标签
如果你的文章是 .mdx，也可以直接使用组件标签（组件已由 PostDetails 全局注册，无需 import）。注意 .mdx 里花括号会被当作 JSX 表达式解析，所以 MDX 文章请用组件标签，::video 指令只适合纯 .md 文章：
<Video id="BV1GJ411x7h7" />
<Video src="/video/demo.mp4" poster="/video/demo.jpg" ratio="9/16" />两种入口共用同一套数据层与视觉，效果完全一致。
瞬间（Moments）里的视频
「瞬间」支持在 frontmatter 里声明视频，无需在正文写任何指令，id 与 src 同样二选一：
---
title: 海边的下午
pubDatetime: 2024-07-01
text: 随手拍的一段海浪。
video:
id: BV1GJ411x7h7
---卡片会出现在瞬间图片区域之后，竖屏视频记得带上 ratio: 9/16，在瀑布流窄栏里比例才正确。
非 B 站链接与失败降级
id 里的内容如果不是 B 站视频（比如其他平台的链接），不会报错，而是自动降级为一张普通的链接卡片；填了 BV 号但接口取数失败时同理，构建始终能正常完成。比如：
youtube.comyoutube.comhttps://www.youtube.com/watch?v=dQw4w9WgXcQ
bilibili.combilibili.comhttps://www.bilibili.com/video/BV0000000000/
第二张卡片就是「BV 号格式正确但视频不存在」的降级效果：渲染为指向 B 站的跳转卡片，一眼就能看出这条引用需要修正。
实现与限制
- 抓取发生在构建期（Node 环境），不会给浏览器增加任何运行时请求；视频信息写入
src/utils/video-cache.json本地缓存，二次构建直接命中、无需联网，也避免触发 B 站接口风控。 - B 站卡片采用「封面门面（facade）」模式：不点击就不加载任何第三方资源，页面保持轻量。
- 展开播放器时会自动暂停页面上其他视频与音乐（含瞬间配乐），避免多重声音打架；但两个平台播放器 iframe 之间无法互相暂停，这是浏览器跨域限制。
- B 站封面有防盗链，卡片已用
referrerpolicy="no-referrer"处理，并把接口返回的http://封面统一升级为https://。 src若误填了网页地址（而非视频文件），构建期会探测内容类型并自动转为平台解析或降级，不会渲染出必然失败的播放器。- 指令段要求整段纯文本，不要混入加粗、行内代码等 Markdown 标记。
- 卡片样式跟随主题的 Light / Dark 两态，也尊重系统的「减少动态效果」偏好。