翻了個底朝天才發現 APlayer 還藏著這幾招

APlayer 是什麼——大多數人只用了它一半的能力

說到 APlayer官網，大家第一反應就是「那個嵌入網頁的音樂播放器」。沒錯，APlayer 最早的確是一款輕量級的 JavaScript 音樂播放器，以清爽的 UI 和靈活的配置著稱，被廣大站長拿去裝飾自己的部落格或作品頁。但很少有人注意到——這貨的生態遠不止一個 <script> 標籤。

首先，APlayer 有對應的 Android APK 版本，作為一款本地音樂播放器，它自動掃描手機裡的 MP3、FLAC、WAV 等格式，按歌手、專輯自動歸類，界面乾淨到幾乎沒有任何多餘的東西。其次，Web 端的 APlayer 配合 MetingJS 可以直接接入網易雲、QQ 音樂等主流平臺的歌單，你連音訊 URL 都不用自己找。最後，它還有一套完整的 API 體系，能讓你用程式控制播放列表、動態切歌、甚至綁定自訂事件。

問題來了——大部分人拿到 APlayer，就是 <div id="aplayer"></div> 加一個 <script>，塞幾首歌進去就完事了。那些藏在 APlayer文檔 深處的參數、API 和配套工具，統統沒被發掘。今天就來扒一扒，這款號稱「零依賴、輕量級」的播放器，到底還藏著哪些讓你眼前一亮的功能。

安裝

APlayer 分兩條線，安裝方式完全不同，這點很多人容易搞混。

Android APK 版的安裝最簡單——APlayer下載 的 APK（體積只有 7.47MB，比大多數單張圖片還小），點擊安裝放行「未知來源」即可。首次啟動會自動掃描手機儲存空間裡的音訊檔案，掃描完成後按歌手、專輯、資料夾三種視圖展示。建議在系統設定裡把 APlayer 的「儲存空間」權限設為允許，否則掃描不到 SD 卡或 USB OTG 裡的音樂。

Web 版的安裝就是引入資源檔案。APlayer 本身無需任何框架依賴，純原生 JS。CDN 引入的話一行就夠，但要注意順序——如果同時用 MetingJS（後面會講），順序必須是：CSS → APlayer.min.js → Meting.min.js，搞反了 MetingJS 會找不到 APlayer 實例。需要 HLS 串流支援的還得額外引入 hls.min.js，而且 hls.js 必須在 APlayer 之前加載，不然 APlayer 初始化時會認為當前環境不支援 HLS。

隱藏功能一：localStorage 記憶用戶偏好——原來可以自訂鍵名

APlayer 有一個被嚴重低估的功能：它會自動把用戶的音量、循環模式（all/one/none）、播放順序（list/random）、歌詞顯隱、列表顯隱這五項設定存進瀏覽器的 localStorage。下次用戶回來，播放器會自動讀取這些值覆蓋程式碼裡的預設值。

這件事幾乎沒有配置成本——你什麼都不用寫，APlayer 幫你搞定了。但大多數人不知道的是，這個存儲行為是可以自訂的，關鍵參數是 storageName。預設鍵名是 'aplayer-setting'，你可以改成任何字串：

const ap = new APlayer({
    container: document.getElementById('aplayer'),
    storageName: 'my-blog-music-setting',
    audio: [...]
});

什麼場景需要改？一個域名下有多個獨立播放器（部落格側邊欄、文章內嵌、彈窗各一個）——它們共用預設鍵名會互相覆蓋設定。又或者你做的是演示頁，需要每次打開都是乾淨的初始狀態，那就給一個每次都變的鍵名（比如加時間戳），等於直接禁用了持久化。

還有一個冷知識：如果你只想臨時改音量但不想讓它被記住，可以用 ap.volume(0.5, true)——第二個參數 true 就是「不寫入 localStorage」。

隱藏功能二：MetingJS 一鍵接入主流音樂平臺——再也不用自己找 URL

這大概是 APlayer 生態裡最被低估的配套工具了。MetingJS 是為 APlayer 設計的配套庫，它調用 Meting API 去獲取網易雲、QQ 音樂、酷狗等平臺的音訊位址、歌詞和封面，然後自動傳給 APlayer 渲染。

換句話說——有了 MetingJS，你連音訊 URL 都不用找了。只需要一行 HTML：

<meting-js
    server="netease"
    type="playlist"
    id="60198"
    theme="#FADFA3">
</meting-js>

這四個參數就能搞定：server 指定平臺（netease、tencent、kugou）、type 指定類型（song/playlist/album/artist/search）、id 就是歌曲或歌單的 ID。MetingJS 會自動創建 APlayer 實例、調用 API、拿到資料、渲染出帶歌詞同步的完整播放器。

支援的平臺列表裡，網易雲（netease）和 QQ 音樂（tencent）是目前最穩定的兩個。蝦米音樂（xiami）已停止服務，不要用。百度音樂偶爾會有解析失敗的情況，屬於 Meting API 或平臺側的調整，不是 APlayer 的問題。

隱藏功能三：播放列表的程序化控制——動態增刪切歌

大多數人用 APlayer 的播放列表就是初始化時塞一個 audio 陣列進去，然後讓用戶在界面上點來點去。但其實 APlayer 提供了完整的 ap.list API，可以用程式在任何時刻操作列表：

• ap.list.add({...}) 或 ap.list.add([...])：動態添加一首歌或一批歌
• ap.list.remove(1)：按下標移除（從 0 開始）
• ap.list.switch(2)：切到指定下標的歌曲
• ap.list.clear()：清空整個列表
• ap.list.toggle()：切換列表顯隱

更酷的是事件繫結——你可以監聽列表的任何變化：

ap.on('listadd', function(audio) { console.log('新增了', audio.name); });
ap.on('listswitch', function(index) { console.log('切到第', index, '首'); });
ap.on('listclear', function() { console.log('列表清空了'); });

這些 API 配合定時器或 WebSocket 能玩出很多花樣——比如後端推送新歌時自動插入列表、根據用戶行為動態排序、甚至做一個多人點歌系統。

隱藏功能四：HLS 串流支援——把 APlayer 當網路收音機

APlayer 不只支援本地音訊檔案，它還支援 HLS（m3u8）串流——也就是網路收音機、直播電臺那種分片加載的音訊格式。但這個功能被很多人忽略，原因是 HLS 的配置比普通 MP3 多了幾個細節要注意。

首先，你得額外引入 hls.js 庫（Safari 用戶例外，它原生支援 HLS），而且必須在 APlayer 之前加載。其次，audio 物件裡要顯式宣告 type: 'hls'，不然 APlayer 會把 m3u8 當普通音訊檔案處理，只有 Safari 能原生播放，其他瀏覽器全部啞火：

audio: [{
    name: '電臺直播',
    url: 'your-live.m3u8',
    type: 'hls'  // 這一行不能少
}]

常見坑還有：m3u8 文件裡的 TS 分片路徑錯了（相對路徑以 m3u8 所在目錄為基準）、CORS 跨域沒開（m3u8 和 TS 分片都要有 Access-Control-Allow-Origin 響應頭）、hls.js 版本太舊與 APlayer 有相容性問題。推薦用 hls.js 1.5.x 穩定版。

哪個坑別踩

最後提一個容易踩的坑：迷你模式下傳入多首歌也不會顯示列表。如果你設了 mini: true，即使 audio 是一個包含十首歌的陣列，列表也會被強制隱藏，用戶只能通過上一首/下一首按鈕或 API 切歌。想讓列表可見就必須把 mini 設為 false——這兩個模式是互斥的。

另外，localStorage 有一個隱患：如果用戶瀏覽器禁用了 localStorage，或者在無痕模式下使用，APlayer 會靜默降級——不會報錯，但所有設置都不會被記住。不是 bug，是設計如此。

收尾

APlayer 給人的印象一直是「簡單好用的輕量播放器」，但簡單不等於功能貧乏。localStorage 自訂鍵名、MetingJS 平臺接入、程序化列表 API、HLS 串流支援——這四個功能加起來，已經能覆蓋從本地播放、網頁嵌入到動態互動的幾乎所有場景。大多數人只用了它三分之一的能力就停下來了，實在可惜。

工具這個東西，用透一點，體驗會完全不同。

本文为个人基于网络公开资料整理编写，非官方内容，仅供学习交流参考；软件版权归原作者所有，请支持正版；使用过程中遇到问题请查阅官方渠道，本文不承担任何责任。