前言¶

在 DSH 裏搭一個能聽歌的浮窗界面，通常會先想到 ncm-player 系列。前幾版有一個反覆出現的問題：歌單裏一旦混進下架或無版權的歌，播放器只彈出一句「播放出錯(可能無版權或需會員)」，然後停在原地，需要手動點下一首。歌單越長、這類歌越多，手動次數就越多。

ncm-player5 是 doctorpancode 維護的派生版本，在 ncm-player4 1.3.1 基礎上只做一處功能改動：檢測到不可播放時自動跳過，繼續播下一首。下面介紹它的定位、繼承的能力、跳過邏輯和安裝方式。

這是什麼¶

一句話定位：DSH（DeepSeek Harness）的網易雲音樂浮窗播放器，完整繼承 ncm-player4，新增自動跳過不可播放歌曲。維護者 doctorpancode，分類爲客戶端插件。

上游是 WolfGenerals/ncm-player。README 把派生鏈寫成一條完整的線性提交歷史，並打了三個 tag：

upstream-1.2.0：上游 WolfGenerals/ncm-player@main 原樣導入，18 個文件逐字節相同，作爲 1.2.0 的公開參照點。
ncm-player4-v1.3.1：ncm-player4 1.3.1，相對 1.2.0 派生出點擊窗口外收起、無操作自動退出、播放心跳、長按拖動、無聲修復。
ncm-player5-v1.4.1：本插件當前版本，相對 1.3.1 的唯一功能改動是自動跳過，另加包名 scope 調整。

也就是說可以執行 git diff ncm-player4-v1.3.1 main，直接審本插件相對基線的全部改動。當前版本 1.4.1，包名 @doctor-pan-code/ncm-player5（早期沿用上游 @wolfgenerals/ scope，但該 scope 屬於上游作者且本插件從未發佈到 npm，故自 1.4.1 起改回投稿人自己的 scope），cordis 加載 id 仍是 ncm-player5。

繼承自 ncm-player4 的能力¶

以下能力與 ncm-player4 1.3.1 一致，均爲 README 列出的既有功能：

播放：播放/暫停、上一首/下一首、進度拖拽、音量與靜音；順序、單曲循環、隨機三種模式。
發現：搜索單曲/歌單/專輯，熱門歌單推薦；登錄後可查看「我的」歌單與收藏的專輯。
歌詞：逐行同步高亮、點擊跳轉、歌詞翻譯；迷你模式顯示當前歌詞，超長歌詞橫向滾動，字號可調。
隊列：添加、移除、清空，自動持久化，重啓後恢復隊列、進度、播放模式、音量。
賬號：網易雲 App 掃碼登錄，或粘貼 Cookie。
浮窗：展開/迷你條/隱藏三種形態，均可拖拽，顏色跟隨 DSH 皮膚主題。
設置：音質、歌詞翻譯、迷你歌詞開關/滾動/字號、無操作自動退出、自動跳過不可播放的歌曲。

既有交互細節：點擊播放窗口以外的區域會收起爲迷你條；收起後 3 秒內無鼠標點擊或移動，自動退出爲右下角音符按鈕，播放不中斷；播放中該按鈕隨音樂低頻鼓點跳動；右下角圖標支持左鍵長按拖動，位置自動記住。

ncm-player5 的新增功能：自動跳過¶

跳過判定分兩道關卡，主判據在地址獲取階段：

地址獲取階段（主判據）：host 半部調用 /api/song/enhance/player/url，網易雲對不可播放的歌曲返回 url: null 且 code: -110。host 把這個信號透傳給前端，songUrl 返回 { url, playable, reason, code }，並新增 songStatus op。當 playable === false 且 reason === 'copyright' 時判定爲無版權/下架，直接跳過，不發起任何音頻請求。
爲了避免把「只是沒有高音質」誤判成「不能播」，songUrl 做了多檔音質降級：請求碼率 → 320k → 192k → 128k → 96k，某檔拿不到地址時自動嘗試更低碼率，全部失敗纔算不可播。
播放出錯階段（兜底）：<audio> 的 error 事件裏，先走原有的兩條重試分支（Web Audio 接管後換新元素、CORS 兜底重載一次），只有重試也用盡，或錯誤碼是 MEDIA_ERR_SRC_NOT_SUPPORTED(4) / MEDIA_ERR_DECODE(3)，才判定爲不可播並跳過。

網絡異常不算不可播：接口本身失敗（超時/斷網/解析失敗）時按「未知」處理，不跳歌，只照舊彈提示。

跳過規則：

按當前播放模式推進。順序模式走下一首，到隊尾回到隊首循環找可播放的；隨機模式隨機換一首並避開當前這首；單曲循環模式下遇到壞歌也會跳到下一首，避免一直重播同一首。
跳過時提示「已跳過《歌名》：無版權/已下架」，2.8 秒後自動消失。
防死循環：連續跳過次數達到隊列長度（上限 30）仍沒有一首能播時，停止播放並只提示一次「隊列中沒有可播放的歌曲」；隊列只有 1 首壞歌時直接停止，不反覆重試。
開關在設置頁 → 播放 →「自動跳過不可播放的歌曲」，默認開啓；關閉後行爲與 ncm-player4 完全一致。
判定結果在 host 側緩存 5 分鐘，避免連跳時對同一首歌反覆請求。

安裝與啓用¶

包名 @doctor-pan-code/ncm-player5，cordis 加載 id 爲 ncm-player5。

注意：本插件與 ncm-player2/3/4 不能同時啓用。host 半部都會註冊 /ncm/api 前綴路由，同時啓用會互相搶佔，安裝本插件時應停用 ncm-player4。

從 GitHub 安裝：

dsh plugin add Doctor-Pan-code/ncm-player5

本地 / 手動安裝（link 方式）與 profile 內其他本地插件一致。先把目錄放到插件目錄，例如 $DSH_HOME/plugins/ncm-player5，然後：

在 $DSH_HOME/profiles/<profile>/package.json 中聲明依賴，並把包追加進 dsh.profile.bundles：

   "dependencies": { "@doctor-pan-code/ncm-player5": "link:C:/Users/<你>/.dsh/plugins/ncm-player5" }

在 $DSH_HOME/profiles/<profile>/cordis.patch.yml 中追加加載項與停用項：

   - insert:
       - id: ncm-player5
         name: '@doctor-pan-code/ncm-player5'
   - id: ncm-player4
     disabled: true

完全退出並重啓 DSH。

數據保存與升級兼容¶

登錄態與播放隊列存放在本機瀏覽器 localStorage，key 仍是 ncmply2-settings；右下角音符按鈕位置 key 仍是 ncmply4-disc-pos。因此從 ncm-player4 升級到 ncm-player5 時，登錄態、播放隊列、各項設置、圖標位置全部自動沿用，不需要重新登錄或重新拖動圖標。

ncm-player5 在 state 裏新增一個字段 autoSkip（默認 true），整體 shape 如下：

{
  "account": { "cookie": "...", "uid": 123, "nickname": "..." },
  "state": {
    "queue": [ { "id": 1, "name": "...", "artists": "...", "album": "...", "cover": "...", "duration": 0 } ],
    "index": -1, "mode": "order", "vol": 0.8, "quality": 320000, "time": 0,
    "showTrans": true, "showMiniLrc": true, "miniLrcScroll": true, "miniLrcSize": 11,
    "autoExit": true, "autoSkip": true
  }
}

host 半部新增的 API¶

本插件在 host 半部新增兩個 op，其餘 search / playlistDetail / albumDetail / lyric / like / 登錄相關 / saveState 等行爲與 ncm-player4 完全一致。

op	入參	返回
`songUrl`	`{ id, br }`	`{ url, playable, reason, code }`；多個碼率依次嘗試，全部失敗時 `url` 仍按舊行爲返回 `song/media/outer/url` 兜底地址以兼容舊前端
`songStatus`	`{ id, br }`	`{ playable, reason, code, fee, freeTrial }`；純查詢，不返回地址，結果緩存 5 分鐘

reason 取值：copyright（code -110，無版權/下架）、error（code -200）、unavailable（其它）、null（可播放或未知）。

適用場景與注意¶

適合想在 DSH 裏掛一個網易雲音樂浮窗、並且希望歌單儘量自動放完的人。插件依賴本機可用的 Node.js 運行時，以及可訪問 music.163.com 的網絡。登錄 Cookie 只用於請求 music.163.com，不發送給任何第三方。收藏（點 ❤）受網易雲賬號風控影響，失敗時會有提示，屬正常現象。僅供個人學習使用，需遵守網易雲音樂服務條款與當地法律法規。

幾點注意：

VIP 專享歌曲在未登錄或非會員時，網易雲同樣返回 -110，因此會被當作不可播放跳過；登錄會員賬號後這些歌可正常播放。
插件以當前 dsh 進程的權限運行，安裝前應檢查源碼與許可證（本插件爲 MIT License）。
本倉庫是社區衍生版本，與 DeepSeek / 幻方無官方從屬關係。

小結¶

ncm-player5 沒有重寫播放器，而是在已成熟的 ncm-player4 基線上補上「遇到下架/無版權歌曲自動跳過」這一個長期痛點。它把跳過判據、音質降級、按模式推進和防死循環處理得比較清楚，同時保留了 ncm-player4 的浮窗交互與全部既有功能。目錄頁與倉庫如下：

目錄頁：https://www.skillhub.cn/plugins/doctorpancode/ncm-player5
GitHub：https://github.com/doctorpancode/ncm-player5

ncm-player5：DSH 裏的網易雲音樂浮窗播放器，核心是自動跳過不可播放歌曲

前言¶

這是什麼¶

繼承自 ncm-player4 的能力¶

ncm-player5 的新增功能：自動跳過¶

安裝與啓用¶

數據保存與升級兼容¶

host 半部新增的 API¶

適用場景與注意¶

小結¶

精选优惠券

ncm-player5：DSH 裏的網易雲音樂浮窗播放器，核心是自動跳過不可播放歌曲

前言¶

這是什麼¶

繼承自 ncm-player4 的能力¶

ncm-player5 的新增功能：自動跳過¶

安裝與啓用¶

數據保存與升級兼容¶

host 半部新增的 API¶

適用場景與注意¶

小結¶

精选优惠券

相關文章