文章中添加音乐播放器

直接URL方式#

1
::music{url="https://example.com/song.mp3" title="歌曲标题" artist="艺术家" cover="封面URL"}

网易云音乐方式#

1
::music{server="netease" type="song" id="1901371647" title="歌曲标题" artist="艺术家"}

代码实现#

1. rehype-component-music-player.mjs（组件，src/plugins/） 解析 ::music{…} 语法 支持参数：url、server、id、type、title、artist、cover、autoplay、loop、volume

2. music-player-script.js（脚本，src/plugins/） 音频播放控制（播放/暂停/进度/音量） Meting API 集成（网易云、QQ音乐等，三级回退） 多播放器互斥暂停、自动播放处理 切页时自动暂停并重新初始化（见下方事件说明）

切页事件的坑：站点用的是 Swup 4 + @swup/astro，它有个兼容层会把 Swup 钩子转成 astro 风格事件派发——content:replace 前触发 astro:before-swap，page:view 触发 astro:page-load。这两个才是实际会触发的事件；Swup v3 时代的 swup:contentReplaced / swup:willReplaceContent 在 4.x 里根本不派发， 写了也白写（会表现为：swup 切进文章时播放器不初始化、切页后音乐不停）。 脚本里监听 astro:before-swap 暂停、astro:page-load 清理并重新初始化。

3. music-player.css（样式，src/styles/） 跟随主题色的扁平卡片风，全部用 Tailwind @apply + 主题变量 暗色模式自动适配（不再手写 .dark 覆盖） 加载中/错误/播放中三个状态类

4. astro.config.mjs（配置）

1
import { MusicPlayerComponent } from "./src/plugins/rehype-component-music-player.mjs";
2
// ...
3
components: {
4
    music: MusicPlayerComponent,
5
}

5. MusicPlayerManager.astro（脚本接入，src/components/features/）

对齐框架里 GithubCardManager 的模式，一行副作用导入脚本，由 Layout 统一渲染：

1
---
2
// 文章内嵌音乐播放器客户端管理器（::music 指令）
3
---
4
<script>
5
  import "@/plugins/music-player-script.js";
6
</script>

Layout.astro 里引入并渲染这个组件即可，不再需要手写 <link> 和 <script src>：

1
import MusicPlayerManager from "@components/features/MusicPlayerManager.astro";
2
// ...
3
<MusicPlayerManager />

6. 样式加载（Markdown.astro / DynamicItemTemplate.astro）

1
import "@/styles/music-player.css";

和 markdown.css、markdown-extend.styl 放在一起，只在有正文的页面（文章、动态）加载，首页等页面不背这份 CSS。