1. 項(xiàng)目概述當(dāng)小愛音箱遇見本地音樂(lè)庫(kù)如果你和我一樣是個(gè)音樂(lè)愛好者家里攢了上百GB的無(wú)損音樂(lè)文件同時(shí)又習(xí)慣了用“小愛同學(xué)”一句話控制家里的燈光、空調(diào)那你可能也遇到過(guò)這個(gè)痛點(diǎn)想用語(yǔ)音隨機(jī)播放自己收藏的音樂(lè)卻發(fā)現(xiàn)小愛音箱只能綁定幾個(gè)有限的在線音樂(lè)平臺(tái)。那些躺在NAS或電腦硬盤里的“私藏”仿佛成了數(shù)字孤島。這個(gè)項(xiàng)目的核心就是打破這個(gè)孤島。它利用一個(gè)運(yùn)行在局域網(wǎng)內(nèi)的Node.js服務(wù)作為“翻譯官”和“調(diào)度員”將存儲(chǔ)在SMB共享比如Windows共享文件夾或NAS中的本地音樂(lè)文件無(wú)縫地對(duì)接到米家和小愛音箱的生態(tài)里。最終實(shí)現(xiàn)的效果是你對(duì)小愛音箱說(shuō)“播放我的音樂(lè)”它就能從你指定的共享文件夾中隨機(jī)挑選一首歌開始播放并且支持連續(xù)播放、切歌等基本操作。這不僅僅是簡(jiǎn)單的文件播放。為了實(shí)現(xiàn)穩(wěn)定、可控的流媒體傳輸項(xiàng)目巧妙地采用了M3U8協(xié)議。服務(wù)端會(huì)動(dòng)態(tài)生成包含音樂(lè)文件真實(shí)網(wǎng)絡(luò)地址的M3U8播放列表小愛音箱通過(guò)米家App則作為一個(gè)標(biāo)準(zhǔn)的HTTP流媒體客戶端來(lái)讀取和播放這個(gè)列表。整個(gè)方案完全在局域網(wǎng)內(nèi)運(yùn)行不依賴任何外網(wǎng)服務(wù)既保護(hù)了隱私又保證了播放的流暢性。適合誰(shuí)來(lái)做如果你對(duì)智能家居聯(lián)動(dòng)有點(diǎn)興趣懂一點(diǎn)基本的命令行操作并且愿意花一兩個(gè)小時(shí)折騰一下那么這個(gè)項(xiàng)目就是為你準(zhǔn)備的。不需要高深的編程知識(shí)我會(huì)把每一步都拆解清楚。2. 核心思路與方案選型為什么不用現(xiàn)成的DLNA或UPnP很多NAS自帶媒體服務(wù)器功能小愛音箱也支持DLNA渲染器。這個(gè)想法很好但實(shí)測(cè)下來(lái)有幾個(gè)問(wèn)題一是DLNA的語(yǔ)音控制體驗(yàn)很差通常需要打開手機(jī)App選擇推送失去了“動(dòng)口不動(dòng)手”的便捷性二是對(duì)音樂(lè)文件列表的隨機(jī)、續(xù)播等邏輯控制不夠靈活。因此我們需要一個(gè)更“主動(dòng)”的方案。2.1 技術(shù)棧拆解為什么是Node.js SMB M3U8整個(gè)方案可以看作一個(gè)微型的流媒體服務(wù)器其技術(shù)選型是經(jīng)過(guò)實(shí)踐權(quán)衡的。Node.js作為服務(wù)端核心我們需要一個(gè)輕量級(jí)、能快速處理HTTP請(qǐng)求、方便進(jìn)行文件系統(tǒng)操作的后端服務(wù)。Node.js基于事件驅(qū)動(dòng)、非阻塞I/O模型非常適合處理大量并發(fā)的網(wǎng)絡(luò)請(qǐng)求比如同時(shí)處理文件列表查詢和音頻流傳輸。它的生態(tài)豐富有現(xiàn)成的smb2庫(kù)可以方便地訪問(wèn)SMB共享也有express這樣的框架能快速搭建Web服務(wù)。相比于Python或JavaNode.js在搭建這種小型工具服務(wù)時(shí)往往更輕便、啟動(dòng)更快。SMB作為存儲(chǔ)協(xié)議SMBServer Message Block是Windows和許多NAS系統(tǒng)默認(rèn)的文件共享協(xié)議幾乎家家戶戶的電腦或NAS都支持。選擇它意味著你的音樂(lè)庫(kù)可以放在家里任何一臺(tái)開啟文件共享的設(shè)備上無(wú)需額外配置FTP或WebDAV通用性最強(qiáng)。我們的Node.js服務(wù)會(huì)扮演一個(gè)“客戶端”去掛載或訪問(wèn)這個(gè)遠(yuǎn)程的SMB共享。M3U8作為傳輸協(xié)議這是實(shí)現(xiàn)穩(wěn)定播放的關(guān)鍵。M3U8本質(zhì)是一個(gè)文本格式的播放列表里面記錄了一系列媒體片段.ts文件或完整媒體文件的網(wǎng)絡(luò)地址。我們這里用它來(lái)傳遞完整的MP3/FLAC等音頻文件地址。對(duì)小愛音箱友好經(jīng)過(guò)測(cè)試小愛音箱內(nèi)置的音頻播放組件能夠很好地解析HTTP服務(wù)提供的M3U8鏈接實(shí)現(xiàn)流暢的流式播放。支持進(jìn)度控制相比于直接提供一個(gè)MP3文件鏈接M3U8協(xié)議能讓播放器小愛音箱更好地支持快進(jìn)、暫停等操作雖然我們項(xiàng)目以隨機(jī)播放為主但協(xié)議本身支持這些特性。動(dòng)態(tài)生成我們可以用Node.js實(shí)時(shí)掃描SMB共享中的音樂(lè)文件動(dòng)態(tài)生成一個(gè)包含隨機(jī)文件鏈接的M3U8列表從而實(shí)現(xiàn)“隨機(jī)播放”的核心功能。2.2 系統(tǒng)架構(gòu)全景圖整個(gè)系統(tǒng)的數(shù)據(jù)流是這樣的理解它有助于后續(xù)的調(diào)試[你的音樂(lè)文件] (存儲(chǔ)在 NAS/PC 的 SMB共享文件夾) | | (SMB協(xié)議訪問(wèn)) V [Node.js 服務(wù)] (運(yùn)行在樹莓派/常開PC/軟路由上) | 1. 掃描并列出音樂(lè)文件 | 2. 隨機(jī)選擇文件 | 3. 生成對(duì)應(yīng)的M3U8播放列表 | 4. 提供HTTP服務(wù) | | (HTTP協(xié)議提供M3U8鏈接) V [米家 App / 小愛音箱] | 1. 通過(guò)“自定義技能”或“本地插件”填入服務(wù)地址 | 2. 請(qǐng)求并解析M3U8 | 3. 按列表順序拉取音頻文件流并播放這個(gè)架構(gòu)中Node.js服務(wù)是中樞它連通了本地存儲(chǔ)和智能音箱。米家App并不直接訪問(wèn)SMB而是訪問(wèn)Node.js服務(wù)提供的標(biāo)準(zhǔn)化HTTP接口這樣極大地簡(jiǎn)化了小愛音箱端的集成難度。注意此方案需要你的Node.js服務(wù)主機(jī)和小愛音箱處于同一個(gè)局域網(wǎng)下并且網(wǎng)絡(luò)質(zhì)量良好以保證音頻流傳輸?shù)姆€(wěn)定性。3. 環(huán)境準(zhǔn)備與核心工具部署工欲善其事必先利其器。這一部分我們先把基礎(chǔ)環(huán)境搭建好確保每個(gè)組件都能正常工作。3.1 Node.js運(yùn)行環(huán)境安裝與避坑我們的服務(wù)端代碼運(yùn)行在Node.js環(huán)境下。安裝Node.js本身很簡(jiǎn)單但版本選擇和一些細(xì)節(jié)容易踩坑。安裝步驟訪問(wèn)官網(wǎng)打開Node.js官方網(wǎng)站下載LTS長(zhǎng)期支持版。目前推薦v18.x或v20.x版本。避免使用最新的奇數(shù)版本如v21.x它們可能不夠穩(wěn)定。Windows/macOS直接運(yùn)行下載的安裝程序基本一路“Next”即可。安裝程序會(huì)自動(dòng)配置環(huán)境變量。Linux (如樹莓派)建議使用NodeSource的倉(cāng)庫(kù)安裝能獲得較新的版本。# 以Ubuntu/Debian為例安裝v20.x LTS curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs驗(yàn)證安裝安裝完成后打開終端Windows是CMD或PowerShellLinux/macOS是Terminal輸入以下命令檢查版本node --version npm --version正常應(yīng)顯示類似v20.11.0和10.2.4的版本號(hào)。常見問(wèn)題與解決‘node‘ 不是內(nèi)部或外部命令說(shuō)明環(huán)境變量未正確配置。Windows用戶請(qǐng)重啟終端或電腦也可在安裝時(shí)勾選“Add to PATH”選項(xiàng)重新安裝。Linux/macOS檢查安裝路徑是否在$PATH中。安裝速度慢或失敗特別是npm install時(shí)這是由于默認(rèn)倉(cāng)庫(kù)在國(guó)外。強(qiáng)烈建議更換為國(guó)內(nèi)鏡像源能提速幾十倍。# 設(shè)置npm淘寶鏡像 npm config set registry https://registry.npmmirror.com # 驗(yàn)證 npm config get registryError: No such module如果運(yùn)行代碼時(shí)出現(xiàn)類似Error: Cannot find module ‘smb2‘的錯(cuò)誤說(shuō)明依賴包沒有安裝。需要進(jìn)入項(xiàng)目目錄執(zhí)行npm install。3.2 SMB共享的配置與訪問(wèn)測(cè)試Node.js服務(wù)需要能讀取你存放音樂(lè)的SMB共享。首先確保你的音樂(lè)庫(kù)已經(jīng)共享。在Windows上配置SMB共享右鍵點(diǎn)擊存放音樂(lè)的文件夾選擇“屬性”。切換到“共享”選項(xiàng)卡點(diǎn)擊“高級(jí)共享”。勾選“共享此文件夾”可以設(shè)置一個(gè)共享名例如MyMusic。點(diǎn)擊“權(quán)限”確保至少給用于訪問(wèn)的用戶或Everyone設(shè)置“讀取”權(quán)限。出于安全考慮在生產(chǎn)環(huán)境建議使用專用賬戶而非Everyone。記下你的電腦的IP地址在CMD中運(yùn)行ipconfig查看和共享名訪問(wèn)地址格式為\\你的IP\MyMusic。在NAS或Linux上通?？梢栽诠芾斫缑嬲业絊MB/CIFS共享服務(wù)設(shè)置過(guò)程類似確保共享目錄有正確的讀取權(quán)限。測(cè)試SMB連通性在運(yùn)行Node.js服務(wù)的機(jī)器上比如樹莓派你需要測(cè)試能否訪問(wèn)這個(gè)共享。Windows測(cè)試在文件資源管理器地址欄直接輸入\\NAS_IP\Music看能否列出文件。Linux測(cè)試可以使用smbclient命令或mount.cifs命令進(jìn)行測(cè)試。安裝客戶端sudo apt install cifs-utils。然后嘗試列出共享smbclient -L //NAS_IP -U 用戶名如果提示輸入密碼后能看到共享列表說(shuō)明連通性沒問(wèn)題。實(shí)操心得很多連接問(wèn)題出在防火墻和SMB版本上。Windows 10/11默認(rèn)可能關(guān)閉了SMB 1.0并開啟了網(wǎng)絡(luò)發(fā)現(xiàn)防火墻規(guī)則。確保在“控制面板-程序和功能-啟用或關(guān)閉Windows功能”中確認(rèn)“SMB 1.0/CIFS文件共享支持”是否被禁用建議禁用但需確?？蛻舳酥С指甙姹?。同時(shí)在防火墻設(shè)置中允許“文件和打印機(jī)共享”規(guī)則。如果Node.js服務(wù)在Linux上訪問(wèn)Windows共享有時(shí)需要指定SMB版本例如在掛載時(shí)使用vers3.0參數(shù)。3.3 項(xiàng)目初始化與核心依賴安裝我們將創(chuàng)建一個(gè)獨(dú)立的項(xiàng)目目錄來(lái)管理代碼。創(chuàng)建項(xiàng)目目錄mkdir xiaoai-local-music cd xiaoai-local-music初始化項(xiàng)目并安裝依賴npm init -y npm install express smb2 m3u8-generatorexpress輕量級(jí)Web框架用于快速搭建提供M3U8和音頻文件流的HTTP服務(wù)器。smb2一個(gè)純JavaScript實(shí)現(xiàn)的SMB2/3客戶端庫(kù)允許Node.js直接訪問(wèn)SMB共享無(wú)需系統(tǒng)掛載。m3u8-generator方便我們以編程方式生成符合規(guī)范的M3U8播放列表文件。創(chuàng)建主文件在項(xiàng)目根目錄下創(chuàng)建一個(gè)名為server.js的文件我們接下來(lái)的代碼都將寫在這里。4. 核心服務(wù)端代碼實(shí)現(xiàn)詳解現(xiàn)在進(jìn)入核心環(huán)節(jié)我們將一步步構(gòu)建server.js。我會(huì)逐段解釋代碼的意圖和關(guān)鍵點(diǎn)。4.1 建立SMB連接與文件遍歷首先我們需要連接到SMB共享并能夠遞歸地掃描其中的音樂(lè)文件。const SMB2 require(smb2); const express require(express); const path require(path); const fs require(fs); const app express(); const PORT 3000; // 服務(wù)運(yùn)行的端口 // 1. 配置SMB連接參數(shù) const smb2Client new SMB2({ share: \\\\192.168.1.100\\MyMusic, // 你的SMB共享地址注意雙反斜杠 domain: WORKGROUP, // 工作組通常Windows是WORKGROUP username: your_username, // 有讀取權(quán)限的用戶名 password: your_password, // 對(duì)應(yīng)用戶的密碼 // autoCloseTimeout: 10000 // 可選自動(dòng)關(guān)閉超時(shí) }); // 支持的音樂(lè)文件擴(kuò)展名 const SUPPORTED_EXT [.mp3, .flac, .wav, .m4a, .aac]; // 2. 遞歸函數(shù)獲取SMB共享中所有音樂(lè)文件列表 async function getAllMusicFiles(dirPath \\) { let fileList []; try { const files await new Promise((resolve, reject) { smb2Client.readdir(dirPath, (err, files) { if (err) reject(err); else resolve(files); }); }); for (const file of files) { const fullPath path.join(dirPath, file.FileName); if (file.FileAttributes.directory) { // 如果是目錄遞歸遍歷 const subFiles await getAllMusicFiles(fullPath); fileList fileList.concat(subFiles); } else { // 如果是文件檢查擴(kuò)展名 const ext path.extname(file.FileName).toLowerCase(); if (SUPPORTED_EXT.includes(ext)) { fileList.push({ name: file.FileName, path: fullPath, size: file.EndOfFile }); } } } } catch (error) { console.error(遍歷目錄 ${dirPath} 時(shí)出錯(cuò):, error); } return fileList; } // 全局變量緩存音樂(lè)文件列表避免每次請(qǐng)求都掃描 let cachedMusicList []; let lastScanTime 0; const SCAN_CACHE_TIME 5 * 60 * 1000; // 緩存5分鐘 async function refreshMusicCache() { if (Date.now() - lastScanTime SCAN_CACHE_TIME || cachedMusicList.length 0) { console.log(正在掃描SMB共享中的音樂(lè)文件...); cachedMusicList await getAllMusicFiles(); lastScanTime Date.now(); console.log(掃描完成共找到 ${cachedMusicList.length} 個(gè)音樂(lè)文件。); } }代碼解讀與注意事項(xiàng)SMB連接smb2庫(kù)使用起來(lái)是異步回調(diào)風(fēng)格我們這里用Promise包裝了一下以便使用async/await讓代碼更清晰。連接參數(shù)中的share地址格式很重要Windows路徑需要雙反斜杠\\。文件遍歷readdir方法返回的文件對(duì)象包含F(xiàn)ileAttributes屬性通過(guò)directory標(biāo)志判斷是文件夾還是文件。遍歷是遞歸進(jìn)行的對(duì)于大型音樂(lè)庫(kù)數(shù)萬(wàn)文件首次掃描可能需要一些時(shí)間。緩存機(jī)制每次HTTP請(qǐng)求都去掃描SMB共享是不現(xiàn)實(shí)的會(huì)非常慢。因此我們引入了緩存邏輯將文件列表在內(nèi)存中緩存5分鐘。你可以根據(jù)你的音樂(lè)庫(kù)更新頻率調(diào)整SCAN_CACHE_TIME。錯(cuò)誤處理SMB網(wǎng)絡(luò)訪問(wèn)可能不穩(wěn)定所以用try...catch包裹了讀取操作避免程序因單個(gè)目錄訪問(wèn)失敗而崩潰。避坑指南smb2庫(kù)在某些情況下可能對(duì)中文路徑或特殊字符的文件名支持不佳。如果發(fā)現(xiàn)掃描不到某些文件可以嘗試將共享路徑和文件名中的中文改為英文測(cè)試。另外確保運(yùn)行Node.js服務(wù)的用戶對(duì)SMB共享有足夠的讀取權(quán)限否則readdir會(huì)返回權(quán)限錯(cuò)誤。4.2 動(dòng)態(tài)生成M3U8播放列表這是實(shí)現(xiàn)播放的核心。當(dāng)小愛音箱請(qǐng)求播放時(shí)我們將從一個(gè)隨機(jī)的文件開始生成一個(gè)包含若干首歌曲的M3U8列表。const m3u8 require(m3u8-generator); // 3. 生成隨機(jī)M3U8播放列表的端點(diǎn) app.get(/playlist.m3u8, async (req, res) { await refreshMusicCache(); if (cachedMusicList.length 0) { return res.status(404).send(未找到可用的音樂(lè)文件。); } const playlistSize 20; // 播放列表包含的歌曲數(shù)量可調(diào)整 const shuffledList [...cachedMusicList].sort(() Math.random() - 0.5); const selectedSongs shuffledList.slice(0, Math.min(playlistSize, shuffledList.length)); // 構(gòu)建M3U8條目 const items selectedSongs.map(song { // 歌曲名作為標(biāo)題文件路徑用于生成播放URL const title path.basename(song.path, path.extname(song.path)); const audioUrl http://${getLocalIp()}:${PORT}/stream?path${encodeURIComponent(song.path)}; return { name: title, duration: -1, // 未知時(shí)長(zhǎng)設(shè)為-1 url: audioUrl }; }); // 生成M3U8內(nèi)容 const playlist m3u8(items, { verbose: true }); res.setHeader(Content-Type, application/vnd.apple.mpegurl); res.send(playlist); }); // 輔助函數(shù)獲取本機(jī)局域網(wǎng)IP用于構(gòu)建完整的音頻流URL function getLocalIp() { const interfaces require(os).networkInterfaces(); for (const iface of Object.values(interfaces)) { for (const config of iface) { if (config.family IPv4 !config.internal) { return config.address; // 通常得到如 192.168.1.5 } } } return localhost; }關(guān)鍵點(diǎn)解析隨機(jī)算法[...cachedMusicList].sort(() Math.random() - 0.5)這是一個(gè)簡(jiǎn)單的數(shù)組隨機(jī)排序方法雖然不是完全均勻的隨機(jī)但對(duì)于這個(gè)場(chǎng)景足夠用了。如果音樂(lè)庫(kù)很大可以考慮更高效的隨機(jī)選取算法。播放列表長(zhǎng)度playlistSize設(shè)置為20意味著一次生成20首歌的列表。小愛音箱會(huì)按順序播放。播放完這20首后如果需要繼續(xù)可以再次請(qǐng)求該端點(diǎn)會(huì)生成一個(gè)新的隨機(jī)列表。你也可以將其設(shè)計(jì)為“無(wú)限”列表但考慮到性能和內(nèi)存分頁(yè)加載更合理。URL構(gòu)建注意audioUrl的構(gòu)建。它指向我們下一個(gè)要?jiǎng)?chuàng)建的/stream端點(diǎn)并將歌曲的SMB路徑作為查詢參數(shù)path傳遞過(guò)去。encodeURIComponent用于確保路徑中的特殊字符如空格、中文被正確編碼。MIME類型Content-Type: application/vnd.apple.mpegurl是M3U8文件的標(biāo)準(zhǔn)MIME類型必須正確設(shè)置播放器才能識(shí)別。獲取本機(jī)IPgetLocalIp()函數(shù)用于自動(dòng)獲取運(yùn)行Node.js服務(wù)的機(jī)器在局域網(wǎng)內(nèi)的IP地址。這樣構(gòu)建出的音頻流URL才能在局域網(wǎng)內(nèi)被小愛音箱正確訪問(wèn)。非常重要如果這里獲取的IP不對(duì)例如獲取到了虛擬機(jī)網(wǎng)卡IP需要手動(dòng)指定。4.3 實(shí)現(xiàn)音頻文件流代理小愛音箱通過(guò)M3U8列表拿到的是形如http://192.168.1.5:3000/stream?path\some\song.mp3的鏈接。我們的/stream端點(diǎn)需要根據(jù)這個(gè)路徑從SMB共享中讀取對(duì)應(yīng)的音頻文件并以流的形式返回給播放器。// 4. 音頻文件流代理端點(diǎn) app.get(/stream, (req, res) { const filePath req.query.path; if (!filePath) { return res.status(400).send(缺少文件路徑參數(shù)。); } console.log(正在流式傳輸: ${filePath}); // 設(shè)置正確的Content-Type根據(jù)文件擴(kuò)展名判斷 const ext path.extname(filePath).toLowerCase(); const mimeType { .mp3: audio/mpeg, .flac: audio/flac, .wav: audio/wav, .m4a: audio/mp4, .aac: audio/aac }[ext] || application/octet-stream; res.setHeader(Content-Type, mimeType); // 支持范圍請(qǐng)求便于播放器跳轉(zhuǎn) res.setHeader(Accept-Ranges, bytes); // 使用SMB2庫(kù)創(chuàng)建文件讀取流 const fileStream smb2Client.createReadStream(filePath); fileStream.on(error, (err) { console.error(讀取文件 ${filePath} 失敗:, err); if (!res.headersSent) { res.status(404).send(文件未找到或無(wú)法讀取。); } }); fileStream.pipe(res); // 將SMB文件流管道到HTTP響應(yīng)流 });技術(shù)細(xì)節(jié)與優(yōu)化MIME類型根據(jù)文件擴(kuò)展名設(shè)置正確的Content-Type頭這能幫助播放器更好地解碼。對(duì)于不認(rèn)識(shí)的類型回退到application/octet-stream。范圍請(qǐng)求Accept-Ranges: bytes這個(gè)頭部很重要。它告訴客戶端小愛音箱這個(gè)資源支持字節(jié)范圍請(qǐng)求。當(dāng)用戶在播放中拖動(dòng)進(jìn)度條時(shí)播放器會(huì)發(fā)送帶有Range頭的請(qǐng)求如Range: bytes5000-服務(wù)器需要處理這個(gè)請(qǐng)求并返回相應(yīng)的文件片段。我們當(dāng)前的簡(jiǎn)單實(shí)現(xiàn)fileStream.pipe(res)對(duì)于完整的GET請(qǐng)求工作良好但對(duì)于Range請(qǐng)求smb2的createReadStream可能需要額外處理。一個(gè)更健壯的實(shí)現(xiàn)是使用express的range中間件或手動(dòng)解析Range頭然后使用smb2Client.read讀取指定字節(jié)范圍。為了簡(jiǎn)化初始版本我們暫時(shí)提供完整文件流大部分播放場(chǎng)景順序、隨機(jī)播放可以工作。如果遇到跳轉(zhuǎn)問(wèn)題可以考慮升級(jí)這部分邏輯。錯(cuò)誤處理流傳輸過(guò)程中可能出錯(cuò)如網(wǎng)絡(luò)中斷、文件被占用我們監(jiān)聽了error事件并嘗試返回404錯(cuò)誤前提是響應(yīng)頭還沒發(fā)送出去!res.headersSent。4.4 啟動(dòng)服務(wù)與測(cè)試最后我們啟動(dòng)Express服務(wù)器并提供一個(gè)簡(jiǎn)單的狀態(tài)頁(yè)。// 5. 啟動(dòng)HTTP服務(wù)器 app.listen(PORT, 0.0.0.0, () { console.log(本地音樂(lè)服務(wù)已啟動(dòng)); console.log(請(qǐng)確保您的手機(jī)/音箱與此服務(wù)器在同一局域網(wǎng)。); console.log(M3U8播放列表地址: http://${getLocalIp()}:${PORT}/playlist.m3u8); console.log(服務(wù)運(yùn)行在: http://0.0.0.0:${PORT}); }); // 可選提供一個(gè)簡(jiǎn)單的狀態(tài)頁(yè)面 app.get(/, (req, res) { res.send( h1小愛音箱本地音樂(lè)服務(wù)/h1 p服務(wù)運(yùn)行正常。/p p音樂(lè)庫(kù)文件總數(shù): span idcount加載中.../span/p pa href/playlist.m3u8 target_blank點(diǎn)擊這里獲取隨機(jī)播放列表(M3U8)/a/p script fetch(/playlist.m3u8) .then(r r.text()) .then(text { // 簡(jiǎn)單解析M3U8計(jì)算條目數(shù) const lines text.split(\\n).filter(l l.startsWith(http)); document.getElementById(count).textContent lines.length; }); /script ); });現(xiàn)在在終端中運(yùn)行node server.js。如果一切正常你將看到輸出的日志其中包含本機(jī)的IP地址和M3U8鏈接。首次測(cè)試在同一局域網(wǎng)的電腦或手機(jī)瀏覽器中訪問(wèn)http://你的服務(wù)器IP:3000/應(yīng)該能看到狀態(tài)頁(yè)。訪問(wèn)http://你的服務(wù)器IP:3000/playlist.m3u8瀏覽器可能會(huì)直接下載一個(gè).m3u8文件用文本編輯器打開它里面應(yīng)該是一系列以http://.../stream?path...開頭的鏈接。復(fù)制其中一個(gè)stream鏈接在瀏覽器中打開如果網(wǎng)絡(luò)正常瀏覽器應(yīng)該開始播放這首音樂(lè)或提示下載。這證明SMB讀取和流傳輸功能是正常的。5. 米家App集成與小愛音箱配置服務(wù)端跑起來(lái)了現(xiàn)在需要讓小愛音箱知道這個(gè)服務(wù)。由于米家官方?jīng)]有直接提供“自定義網(wǎng)絡(luò)音頻源”的功能我們需要用一個(gè)“曲線救國(guó)”的方法。5.1 利用“自定義技能”或“本地插件”概念目前讓小愛音箱播放自定義網(wǎng)絡(luò)流的最可行方法是通過(guò)“小愛音箱自定義技能”或一些第三方工具如miot-auto在局域網(wǎng)內(nèi)模擬一個(gè)設(shè)備。但這對(duì)普通用戶門檻較高。更實(shí)用的一種方法是利用米家App中的“本地TTS”或“網(wǎng)絡(luò)電臺(tái)”類插件思路但我們需要的是一個(gè)穩(wěn)定的集成。這里介紹一個(gè)經(jīng)過(guò)驗(yàn)證的相對(duì)簡(jiǎn)單方法將我們的M3U8鏈接偽裝成一個(gè)網(wǎng)絡(luò)電臺(tái)流。許多智能音箱支持添加自定義網(wǎng)絡(luò)電臺(tái)通過(guò)URL。雖然小愛音箱App沒有直接提供圖形化界面添加但我們可以通過(guò)開發(fā)者模式或利用已有的“訓(xùn)練計(jì)劃”觸發(fā)一個(gè)包含URL的指令。實(shí)際操作步驟以小米音箱Pro為例獲取穩(wěn)定的服務(wù)地址確保你的Node.js服務(wù)在局域網(wǎng)內(nèi)有一個(gè)固定的IP地址。最好在路由器中為運(yùn)行服務(wù)的設(shè)備如樹莓派設(shè)置靜態(tài)IPDHCP保留防止IP變化導(dǎo)致鏈接失效。構(gòu)造最終播放URL我們的播放入口是http://你的靜態(tài)IP:3000/playlist.m3u8。通過(guò)米家App“訓(xùn)練計(jì)劃”實(shí)現(xiàn)如果支持打開米家App進(jìn)入你的小愛音箱設(shè)備頁(yè)面。尋找“訓(xùn)練計(jì)劃”、“智能場(chǎng)景”或“自動(dòng)化”功能。創(chuàng)建一個(gè)新的場(chǎng)景觸發(fā)條件可以選擇“手動(dòng)執(zhí)行”或“定時(shí)”。在執(zhí)行動(dòng)作中選擇“設(shè)備控制” - 你的小愛音箱 - “播放指定文字”。在文字內(nèi)容中嘗試輸入包含URL的指令。注意經(jīng)過(guò)測(cè)試直接輸入U(xiǎn)RL可能不會(huì)被正確解析為音頻源。成功率更高的方法是使用小愛同學(xué)支持的特定語(yǔ)音指令模板。更可靠的方法使用語(yǔ)音指令直接觸發(fā)經(jīng)過(guò)社區(qū)測(cè)試對(duì)小愛音箱說(shuō)“小愛同學(xué)播放網(wǎng)絡(luò)電臺(tái) [你的M3U8鏈接]”。部分型號(hào)的小愛音箱會(huì)嘗試解析并播放這個(gè)鏈接。但這需要每次都說(shuō)一長(zhǎng)串URL不實(shí)用。我們可以將這句指令設(shè)置為一個(gè)捷徑或場(chǎng)景。重要提示米家和小愛音箱的固件版本不斷更新對(duì)自定義音頻源的支持策略也可能變化。上述方法在部分型號(hào)和固件版本上有效但不是官方標(biāo)準(zhǔn)功能。最穩(wěn)定且強(qiáng)大的方式是使用miot-auto、XiaoMi Miot Auto等第三方Home Assistant集成或開源項(xiàng)目它們可以在局域網(wǎng)內(nèi)完全模擬一個(gè)媒體播放器設(shè)備并暴露給米家App。但這涉及到Home Assistant的部署復(fù)雜度更高。對(duì)于本項(xiàng)目我們優(yōu)先保證服務(wù)端的健壯性客戶端集成可以探索上述方法。5.2 備選方案使用其他支持自定義源的App如果米家App集成困難可以考慮使用其他能夠接收網(wǎng)絡(luò)音頻流并推送到小愛音箱的App。例如一些第三方音樂(lè)播放器App如BubbleUPnP for Android支持將手機(jī)作為媒體服務(wù)器并推送到DLNA渲染器小愛音箱支持DLNA。你可以在手機(jī)App中添加我們的M3U8鏈接作為源然后推送到音箱。這相當(dāng)于用手機(jī)App做了一次中轉(zhuǎn)。6. 服務(wù)優(yōu)化與進(jìn)階玩法基礎(chǔ)功能跑通后我們可以從性能、功能和穩(wěn)定性上進(jìn)行優(yōu)化。6.1 性能優(yōu)化與緩存策略文件列表緩存優(yōu)化之前的緩存是簡(jiǎn)單的定時(shí)刷新?？梢愿倪M(jìn)為“惰性刷新文件系統(tǒng)事件監(jiān)聽”。例如使用chokidar庫(kù)需要SMB支持或通過(guò)輪詢監(jiān)聽SMB共享目錄的變化需謹(jǐn)慎SMB的監(jiān)聽可能不可靠或者僅在文件列表為空或用戶強(qiáng)制刷新時(shí)才重新掃描。音頻流傳輸優(yōu)化啟用Gzip壓縮對(duì)于M3U8文本文件可以在Express中啟用壓縮中間件減少傳輸數(shù)據(jù)量。const compression require(compression); app.use(compression());處理Range請(qǐng)求如前所述實(shí)現(xiàn)完整的Range請(qǐng)求支持以允許播放器跳轉(zhuǎn)和緩沖。這需要解析req.headers.range并使用smb2Client.read讀取特定字節(jié)范圍。app.get(/stream, async (req, res) { const filePath req.query.path; // ... 獲取文件大小和MIME類型 ... const fileSize await getFileSizeViaSMB(filePath); // 需要實(shí)現(xiàn)此函數(shù) const range req.headers.range; if (range) { const parts range.replace(/bytes/, ).split(-); const start parseInt(parts[0], 10); const end parts[1] ? parseInt(parts[1], 10) : fileSize - 1; const chunksize (end - start) 1; res.writeHead(206, { Content-Range: bytes ${start}-${end}/${fileSize}, Accept-Ranges: bytes, Content-Length: chunksize, Content-Type: mimeType, }); // 使用smb2Client.read讀取指定范圍并寫入響應(yīng)流 const buffer await readFileRangeViaSMB(filePath, start, end); res.end(buffer); } else { // 沒有Range請(qǐng)求發(fā)送整個(gè)文件 res.writeHead(200, { Content-Length: fileSize, Content-Type: mimeType }); const fileStream smb2Client.createReadStream(filePath); fileStream.pipe(res); } });服務(wù)進(jìn)程守護(hù)確保Node.js服務(wù)在后臺(tái)穩(wěn)定運(yùn)行崩潰后能自動(dòng)重啟?？梢允褂孟到y(tǒng)級(jí)工具如systemd(Linux)、pm2(跨平臺(tái)) 或forever。# 使用PM2守護(hù)進(jìn)程 npm install -g pm2 pm2 start server.js --name xiaoai-music pm2 save pm2 startup # 設(shè)置開機(jī)自啟6.2 功能擴(kuò)展播放列表與歌單管理固定歌單除了隨機(jī)播放可以增加按目錄、專輯或藝術(shù)家生成播放列表的功能。例如新增端點(diǎn)/playlist/album/:name掃描特定文件夾。播放歷史與偏好在服務(wù)端記錄播放歷史甚至可以基于簡(jiǎn)單的算法如播放次數(shù)進(jìn)行加權(quán)隨機(jī)避免某些歌曲永遠(yuǎn)播不到。Web控制界面使用express提供靜態(tài)文件服務(wù)做一個(gè)簡(jiǎn)單的HTML頁(yè)面展示音樂(lè)庫(kù)允許用戶選擇專輯、創(chuàng)建播放列表然后生成對(duì)應(yīng)的M3U8鏈接。甚至可以集成一個(gè)簡(jiǎn)單的播放器進(jìn)行預(yù)覽。支持更多音頻格式擴(kuò)展SUPPORTED_EXT數(shù)組增加如.ogg,.ape,.dsf等格式。注意小愛音箱的硬件解碼能力有限可能不支持所有格式最穩(wěn)妥的是MP3和AAC。6.3 安全性與網(wǎng)絡(luò)考慮訪問(wèn)控制目前服務(wù)運(yùn)行在0.0.0.0意味著局域網(wǎng)內(nèi)任何設(shè)備都能訪問(wèn)。如果你不希望這樣可以設(shè)置防火墻規(guī)則只允許小愛音箱的IP地址訪問(wèn)3000端口?；蛘咴贓xpress中添加簡(jiǎn)單的HTTP Basic認(rèn)證。const auth require(basic-auth); app.use(/playlist.m3u8, (req, res, next) { const user auth(req); if (!user || user.name ! admin || user.pass ! your_password) { res.set(WWW-Authenticate, Basic realmMusic Server); return res.status(401).send(需要認(rèn)證); } next(); });注意Basic認(rèn)證密碼是明文傳輸僅適用于低安全需求的局域網(wǎng)環(huán)境。SMB憑證管理將SMB的用戶名和密碼硬編碼在代碼中不安全。應(yīng)該使用環(huán)境變量或配置文件。# 啟動(dòng)時(shí)傳入環(huán)境變量 SMB_USERmyuser SMB_PASSmypass node server.js// 在代碼中讀取 const smb2Client new SMB2({ share: process.env.SMB_SHARE, username: process.env.SMB_USER, password: process.env.SMB_PASS, // ... });7. 常見問(wèn)題排查與解決實(shí)錄在實(shí)際部署過(guò)程中你幾乎一定會(huì)遇到一些問(wèn)題。這里記錄了我踩過(guò)的坑和解決方案。7.1 服務(wù)啟動(dòng)與網(wǎng)絡(luò)連接問(wèn)題問(wèn)題現(xiàn)象可能原因排查步驟與解決方案Error: connect ECONNREFUSED啟動(dòng)時(shí)報(bào)錯(cuò)端口被占用1. 換一個(gè)端口如8080。2. 查找占用端口的進(jìn)程并結(jié)束lsof -i:3000(Linux/macOS) 或netstat -ano | findstr :3000(Windows)。瀏覽器無(wú)法訪問(wèn)http://IP:3000防火墻阻止1.服務(wù)器防火墻確保3000端口已開放。Linux:sudo ufw allow 3000/tcpWindows在防火墻高級(jí)設(shè)置中添加入站規(guī)則。2.路由器/網(wǎng)絡(luò)隔離確認(rèn)手機(jī)/音箱和服務(wù)器在同一子網(wǎng)且沒有開啟“AP隔離”或“客戶端隔離”功能。SMB連接失敗readdir返回權(quán)限錯(cuò)誤SMB認(rèn)證失敗或網(wǎng)絡(luò)路徑錯(cuò)誤1. 檢查SMB共享地址、用戶名、密碼是否正確。2. 嘗試在服務(wù)器上用命令行工具如smbclient連接SMB驗(yàn)證憑證。3. 檢查SMB共享的權(quán)限確保運(yùn)行Node.js服務(wù)的系統(tǒng)用戶有讀取權(quán)限。4. 嘗試在Windows共享設(shè)置中暫時(shí)啟用“Guest”賬戶或?yàn)椤癊veryone”添加讀取權(quán)限進(jìn)行測(cè)試。能訪問(wèn)M3U8但無(wú)法播放音頻流/stream端點(diǎn)邏輯錯(cuò)誤或文件路徑問(wèn)題1. 在瀏覽器中直接打開一個(gè)/stream?path...鏈接看是下載文件還是報(bào)錯(cuò)。2. 查看Node.js服務(wù)日志確認(rèn)fileStream是否有error事件。3. 檢查filePath是否包含中文字符或特殊字符encodeURIComponent和decodeURIComponent是否配對(duì)使用。7.2 播放與音質(zhì)問(wèn)題問(wèn)題現(xiàn)象可能原因排查步驟與解決方案小愛音箱說(shuō)“無(wú)法播放”或沒反應(yīng)語(yǔ)音指令格式不對(duì)或音箱不支持1. 先用手機(jī)瀏覽器訪問(wèn)M3U8鏈接確保能正常下載且內(nèi)容正確。2. 在手機(jī)端用支持網(wǎng)絡(luò)流的音頻播放器App如VLC打開M3U8鏈接測(cè)試是否能播放。3. 嘗試對(duì)小愛音箱說(shuō)更具體的指令“小愛同學(xué)播放網(wǎng)絡(luò)音頻 [URL]”或“小愛同學(xué)播放在線電臺(tái) [URL]”。不同型號(hào)固件支持度不同。4.終極測(cè)試使用一個(gè)已知可播的公共網(wǎng)絡(luò)電臺(tái)M3U8鏈接如一個(gè)MP3流鏈接測(cè)試音箱功能如果也不行說(shuō)明音箱本身不支持或功能被限制。播放卡頓、斷斷續(xù)續(xù)網(wǎng)絡(luò)帶寬不足或服務(wù)器性能瓶頸1. 檢查服務(wù)器如樹莓派的CPU和內(nèi)存使用率在播放時(shí)是否過(guò)高。2. 檢查網(wǎng)絡(luò)在服務(wù)器和音箱之間進(jìn)行網(wǎng)絡(luò)測(cè)速如用iperf3。3.優(yōu)化確保服務(wù)器通過(guò)有線網(wǎng)絡(luò)以太網(wǎng)連接路由器音箱也盡量使用5GHz Wi-Fi。4. 嘗試降低音頻文件碼率轉(zhuǎn)碼或者服務(wù)端在流傳輸時(shí)進(jìn)行實(shí)時(shí)轉(zhuǎn)碼需要ffmpeg復(fù)雜度高。只能播放幾秒就停止M3U8列表或流傳輸問(wèn)題1. 檢查生成的M3U8文件確保每個(gè)#EXTINF標(biāo)簽后的duration值不為0或過(guò)小。我們之前設(shè)為-1未知大部分播放器能處理?？梢試L試估算時(shí)長(zhǎng)并填入真實(shí)值。2. 檢查音頻流響應(yīng)頭是否正確特別是Content-Type和Content-Length如果可能。3. 可能是播放器對(duì)Range請(qǐng)求的支持問(wèn)題。嘗試實(shí)現(xiàn)完整的Range請(qǐng)求支持見6.1節(jié)。播放列表不是隨機(jī)的隨機(jī)算法或緩存問(wèn)題1. 檢查/playlist.m3u8端點(diǎn)每次訪問(wèn)返回的列表是否不同。在瀏覽器中多次刷新查看。2. 確認(rèn)cachedMusicList在每次請(qǐng)求時(shí)是否被正確打亂。我們的sort隨機(jī)算法在數(shù)組很大時(shí)可能不夠“亂”可以考慮使用 Fisher-Yates洗牌算法 。7.3 長(zhǎng)期運(yùn)行與維護(hù)服務(wù)意外停止使用進(jìn)程守護(hù)工具pm2并配置日志輪轉(zhuǎn)和內(nèi)存監(jiān)控。pm2 logs xiaoai-music --lines 100 # 查看日志 pm2 monit # 監(jiān)控資源使用音樂(lè)庫(kù)更新后服務(wù)不識(shí)別目前是定時(shí)緩存可以增加一個(gè)手動(dòng)刷新緩存的API端點(diǎn)。app.post(/refresh-cache, async (req, res) { cachedMusicList []; lastScanTime 0; await refreshMusicCache(); res.send(音樂(lè)庫(kù)緩存已刷新。); });SMB連接超時(shí)或斷開smb2庫(kù)在網(wǎng)絡(luò)不穩(wěn)定時(shí)可能斷開?？梢栽趧?chuàng)建SMB2客戶端時(shí)配置重試和超時(shí)參數(shù)并添加錯(cuò)誤監(jiān)聽在連接斷開時(shí)嘗試重新初始化。smb2Client.on(error, (err) { console.error(SMB客戶端發(fā)生錯(cuò)誤:, err); // 可以在這里嘗試重新連接 });部署這個(gè)項(xiàng)目最大的成就感莫過(guò)于對(duì)著音箱說(shuō)一句“播放我的音樂(lè)”它就開始娓娓道來(lái)那些精心收藏的曲目那種無(wú)縫銜接的體驗(yàn)是任何在線音樂(lè)平臺(tái)都無(wú)法提供的專屬感。整個(gè)過(guò)程里最關(guān)鍵的其實(shí)不是代碼而是耐心調(diào)試網(wǎng)絡(luò)和兼容性的那部分。比如確保你的服務(wù)IP是固定的搞清楚路由器里有沒有開隔離這些看似瑣碎的細(xì)節(jié)往往就是成功與否的分水嶺。如果遇到音箱不認(rèn)M3U8鏈接的情況別灰心先用VLC這類播放器在電腦或手機(jī)上測(cè)試確保鏈接本身是通的、格式是對(duì)的把問(wèn)題范圍縮小到服務(wù)端排查起來(lái)就更有方向了。