写博客或记录瞬间时，经常想顺手放一首当下循环的歌，当作文章的配乐。直接贴一个音乐链接显得生硬，放一张截图又没法点开听。于是本站新增了「音乐卡片」：在文章里写一行指令，构建时会自动抓取歌曲的封面、歌名与歌手，渲染成一张黑胶风格的小卡片，点击就能跳转到对应平台收听。

下面用几个例子演示它的用法，也是这篇文章本身的真实渲染效果。

语法

音乐卡片由 ::music 指令构成，必须独立成段书写：

::music{id=歌曲ID}
::music{id=歌曲ID platform=netease}

• id 是必填项，对应网易云音乐的歌曲 ID（歌曲播放页链接里 id= 后面的那串数字）。
• platform 默认是 netease（网易云音乐），未来可扩展 qq / spotify / apple。
• 不加任何参数时，歌曲信息会在构建期自动抓取并写入本地缓存，后续构建不再联网。

一篇文章里的配乐

最常见的情况，在正文里随手放一张卡片：

构建时插件会请求网易云的非官方接口，取出歌曲名称、歌手与封面，渲染成一张黑胶唱片样式的小卡。卡片随主题的 Light / Dark 两态变化，移动端也会自动缩放。

在 MDX 里用组件标签

如果你的文章是 .mdx，也可以直接使用组件标签，写法更直观：

<Music id="212233" />

<Music id="212233" platform="netease" />

两种入口最终共用同一套视觉与数据层，效果完全一致。纯 .md 文章请用上面的 ::music 指令。

瞬间（Moments）里的配乐

「瞬间」支持在 frontmatter 里声明配乐，无需在正文写任何指令：

---
title: 我的夏天
pubDatetime: 2024-07-01
text: 海边的风，和这首循环了一下午的歌。
music:
  platform: netease
  id: 212233
---

卡片会出现在瞬间正文的配乐区域，风格与文章内保持一致。

失败降级

如果抓取失败（接口限流、网络不通，或歌曲 ID 不存在），卡片不会报错，而是降级为「黑胶占位 + 歌名兜底」的可点击卡片，构建始终能正常完成。例如下面这个不存在的 ID：

实现与限制

• 抓取发生在构建期（Node 环境），不会给浏览器增加任何运行时请求；歌曲信息会被写入 src/utils/music-cache.json 本地缓存，二次构建直接命中、无需联网。
• 第一版只做「展示 + 跳转」，不实现在线播放器，避免引入大型播放器依赖、也不影响静态生成。
• 封面图直接引用网易云 CDN，不下载到本地；若该 CDN 有防盗链导致图片裂开，会自动回退为纯 CSS 黑胶占位。
• 指令段要求整段纯文本，不要混入加粗、行内代码等 Markdown 标记。
• 卡片样式跟随主题的 Light / Dark 两态，也尊重系统的「减少动态效果」偏好。

如果你在文章里看到某张卡片显示异常，多半是抓取未拿到可用信息，给它换个有效的歌曲 ID，或在 music-cache.json 里手动补一条记录即可。