APlayer 音乐播放器使用教程

APlayer 是一个轻量的 HTML5 音乐播放器，适合放在博客文章、个人主页或音乐专题页里。它负责播放器界面和播放控制，歌曲名称、作者、封面与音频地址则由我们自己提供。

这篇文章既是一份从零开始的使用记录，也是当前页面的实际实现。页面只在 aplayer: true 时输出初始化脚本，APlayer 资源、封面与音频都要等用户点击后才会请求。

在线演示

下面的播放器直接使用 APlayer 创建，不依赖 MetingJS 或第三方歌单解析接口。先点击加载播放器，再点击播放即可试听；点击前不会请求封面或音频。

演示使用网易云音乐外链；播放器出现后仍无法播放时，应分别检查外链可用性与 APlayer 初始化状态。

最简单的接入方式

普通 HTML 页面只需要完成三件事：加载样式与脚本、准备容器、创建 APlayer 实例。

1. 引入 APlayer

这里固定使用 1.10.1 版本，避免 CDN 上的最新版变化影响已有页面。顺带一提，1.10.1 是 APlayer 在 2018 年发布的最后一个版本，项目此后多年没有更新，固定版本在这反而是稳妥做法。

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/aplayer@1.10.1/dist/APlayer.min.css"
>
<script src="https://cdn.jsdelivr.net/npm/aplayer@1.10.1/dist/APlayer.min.js"></script>

2. 添加播放器容器

容器本身不需要写内容，APlayer 初始化后会把完整界面渲染进去。

<div id="aplayer"></div>

3. 初始化播放器

container 用来指定渲染位置，audio 保存歌曲信息。

<script>
  const player = new APlayer({
    container: document.getElementById('aplayer'),
    audio: {
      name: '希望有羽毛和翅膀',
      artist: '知更鸟 / HOYO-MiX / Chevy',
      url: 'https://music.163.com/song/media/outer/url?id=2155423468.mp3',
      cover: 'https://p1.music.126.net/aR4BlDNkA84tFbg8bBpriA==/109951169585655912.jpg',
      theme: '#51a8dd'
    }
  });
</script>

至此，一个最基础的单曲播放器就完成了。实际项目里建议把初始化代码放到独立 JavaScript 文件中，方便维护，也能避免文章内容和交互逻辑混在一起。

配置多首歌曲

把 audio 改成数组，就能得到带播放列表的播放器。listFolded 控制列表是否默认收起。若要求点击前完全不请求音频，应使用 preload: 'none'，并把播放器初始化本身也放到用户操作之后。

const player = new APlayer({
  container: document.getElementById('aplayer'),
  listFolded: false,
  preload: 'none',
  audio: [
    {
      name: '歌曲 A',
      artist: '歌手 A',
      url: 'https://example.com/audio-a.mp3',
      cover: 'https://example.com/cover-a.jpg'
    },
    {
      name: '歌曲 B',
      artist: '歌手 B',
      url: 'https://example.com/audio-b.mp3',
      cover: 'https://example.com/cover-b.jpg'
    }
  ]
});

常用字段如下：

使用网易云音乐外链

网易云音乐的歌曲页面地址不能直接作为音频地址。常见的外链格式如下，其中 id 是歌曲页面 URL 里的歌曲编号。

歌曲页面：https://music.163.com/song?id=2155423468
音频外链：https://music.163.com/song/media/outer/url?id=2155423468.mp3

需要注意，外链是否可播取决于歌曲版权和网易云的访问策略。付费、仅客户端可播或地区受限的歌曲可能返回错误内容，因此正式使用前应在无登录状态下测试。

在 Astro 中只为指定文章加载

本站没有把 APlayer 放进全局布局，而是在文章 frontmatter 中增加开关：

---
title: "APlayer 音乐播放器使用教程"
aplayer: true
---

内容集合需要声明这个字段，否则它不会成为可靠的类型化文章数据：

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    aplayer: z.boolean().optional()
  })
});

文章详情页读取开关，并仅在需要时输出初始化脚本：

---
const hasAPlayerDemo = entry.data.aplayer === true;
---

<Content />

{hasAPlayerDemo && (
  <script
    src="/js/post-aplayer-demo.js"
    defer
    data-astro-rerun
    data-cfasync="false"
  ></script>
)}

这样生成其他文章时不会出现这段标签。音乐文章中的脚本只绑定加载按钮，按钮点击后才请求 APlayer 的 CSS、JavaScript 与媒体。data-astro-rerun 让脚本在 Astro View Transitions 切换到这篇文章后重新执行，初始化脚本还需要在离页清理中暂停并销毁播放器。

为什么不用 MetingJS

MetingJS 可以根据网易云歌单 ID 自动获取歌曲资料，写法确实很短：

<meting-js server="netease" type="playlist" id="162905309"></meting-js>

但它并不是只靠浏览器和网易云就能工作，通常还需要一个 Meting API 服务负责解析歌单。API 不可用、请求被拦截或返回格式变化时，页面可能只剩一个空白区域，很难区分是播放器出错还是歌单解析失败。

因此这篇教程的演示直接向 APlayer 传入歌曲信息。代码多几行，但加载链路更清楚，出了问题也更容易判断。

常见问题

页面完全没有播放器

先打开浏览器开发者工具，检查 APlayer 的 CSS 和 JavaScript 是否成功返回。如果 CDN 被网络策略拦截，可以把对应文件下载到站点本地，再把地址换成 /css/APlayer.min.css 与 /js/APlayer.min.js。

播放器出现但歌曲不能播放

直接在新标签页打开 url。如果浏览器不能播放或下载到的不是音频文件，就需要更换音频源；这与 APlayer 的界面初始化无关。

页面切换后出现两个播放器

这通常是重复初始化造成的。给容器添加初始化标记，并在离开页面时调用 player.destroy()，就能避免 Astro 客户端路由反复绑定实例。

自动播放没有生效

现代浏览器通常禁止未经过用户操作的有声自动播放。即使设置 autoplay: true，也不能保证页面打开后立即播放，保留用户点击播放是更稳定的选择。

小结

APlayer 只负责播放界面，真正决定能否播放的是音频地址。单曲或少量歌单可以直接维护 audio 配置；需要自动同步平台歌单时再考虑 MetingJS，同时为解析 API 不可用的情况准备提示或降级方案。

本站采用的是前一种方式：文章直接保存网易云演示地址，独立脚本在用户点击后加载和初始化，aplayer: true 负责限定脚本范围。这样其他页面保持轻量，音乐文章在点击前也不会产生媒体流量。