有些文章适合安静读，有些则适合配上一首歌。本站的 /Music 指令就是为后者准备的：在正文里单独写一行网易云链接，构建时会解析出歌曲 id，阅读页侧栏挂上可交互播放器，指令位置则变成一张只读的引用卡片。
下面这一行在渲染后应当从正文中消失，并驱动侧栏播放与文内引用卡：
为什么要在文章里嵌音乐
技术博客多数时候在讲方案、贴代码、记踩坑。偶尔也会想写一点更「场景化」的内容——比如某次深夜改 bug 时循环的歌，或某段旅行路上反复听的副歌。把音乐嵌进文章，不是为了做成流媒体站，而是让阅读节奏和情绪背景能对齐。
约定很简单：
- 指令必须单独成行；
- 支持完整链接或纯数字 id，中英文冒号均可；
- 同一篇文章里若出现多条，以第一条作为侧栏自动播放曲目；
- 正文位置只展示封面、歌名、歌手，不可交互，避免和侧栏播放器抢控制权。
构建与缓存在做什么
访客打开文章时，不应再依赖临时播放直链。当前流程是：
- 构建期：扫描所有文章的
/Music，拉取元数据与歌词，下载音频到static/media/music/{id}.mp3，封面本地化到同目录，并写入music-cache.json； - 运行期：播放器与引用卡优先读本地文件；本地齐全时构建会跳过 API，省额度、也更稳；
- 降级：若某次构建没能下到音频，前端仍可回退实时接口，但不影响正文阅读。
对作者来说，日常只需要改 Markdown 和推送；对读者来说，听感是「站点自己的静态资源」，而不是一串随时过期的外链。
阅读时的交互预期
侧栏播放器（大屏可见）应具备：
- 封面、歌名、歌手；
- 播放 / 暂停；
- 进度条拖动与键盘微调；
- 音量滑条与静音（音量会记在浏览器本地）；
- 实时歌词（有译文则当前行附带）。
文内引用卡则刻意克制：左侧竖线、小字「引用」、封面与曲名信息，点不动、也不抢焦点。浏览器若拦截自动播放，侧栏会提示需要一次点击——这是平台策略，不是站点故障。
写作时可以这样用
适合用 /Music 的场景包括：
- 听感笔记：写完一首歌的结构或编曲细节，顺手挂上原曲；
- 场景日记：某一天的天气、通勤、心情，用一首歌收束；
- 专题连载：同一主题下多篇文章共用不同曲目，形成「配乐年表」。
不适合的情况也要心里有数：版权敏感的长文、需要精确对照多轨的教程、或读者明确需要安静阅读的文档，就不必强行加音乐。功能是可选的，不是每篇的标配。
自检清单
改完这篇或新写一篇后，可以快速自检：
- 指令行是否在预览中消失，并出现引用卡；
- 侧栏是否加载到正确曲目（本篇应为 id
988223）； - 音频地址是否为
/media/music/988223.mp3一类本地路径（缓存命中时）； - 移动端布局是否仍可读（侧栏可能隐藏，引用卡仍应在正文中）；
- 构建日志是否对已缓存曲目打印「跳过 API」。
收束
音乐是背景，文字才是主线。/Music 只做一件事：让作者用最小语法，把「此刻想让你听到的那一首」放进文章结构里。
若侧栏已响起，不妨顺着歌词往下读完本页；若浏览器要求手势，点一下播放即可。之后你就可以在自己的文章里，用同一行指令挂上属于那篇文章的声音。