文章目录
- 📖 介绍 📖
- 🏡 演示环境 🏡
- 📒 从零做一个洛雪音源：契约、容错、校验与维护 📒
- 🧩 先建立认知：音源脚本到底负责什么
- 🧭 一句话定位
- 📜 官方 API 契约
- 🕳️ 踩坑实录：七个真实的坑
- 🕳️ 后端返回的直链，立刻就失效
- 📄 返回 200，内容却是网页
- 🎭 最隐蔽的一个：请求 FLAC，拿到的是 128k
- ⏸️ 能播，但 11 秒后断了
- 🈶 中文路径导致的编码崩溃
- 🗣️ 同一个参数，酷狗不认
- 🎵 最有教训感的一个：放出来的不是那首歌
- 🏗️ 从零到上线：六步完整流程
- 🧠 认知准备
- 🛠️ 搭最小可用源
- 🛡️ 引入三件套
- 📖 全平台接入
- 🚀 部署到 GitHub Pages
- ✅ 客户端端到端验收
- 🩺 每周自动维护
- 🩺 健康检测流水线
- 📊 实测数据（45 组合探测，实测于 2026-10）
- ⚓️ 相关链接 ⚓️
📖 介绍 📖
用洛雪音乐这类播放器的人都遇到过：导入一个网上找的音源，前几天好使，过一阵就「播放失败」——不是源文件坏了，是它背后依赖的解析接口失效了。免费后端本来就时效性强，别人的源你没法维护，失效了只能再找一个。
这篇讲一条不一样的路：自己写一个音源。不需要服务器，一个 GitHub 账号加上本机的 Node.js 就够了。音源本体是一个纯 JS 脚本，托管在 GitHub Pages 上拿到恒定直链，再配一个每周自动体检的维护脚本，后端失效能自动感知、自动切换。
先把最容易走弯路的认知摆正：这类播放器的自定义音源只干一件事——把客户端递过来的歌曲 ID 换成一条能播的 HTTP 直链。搜索、歌词、封面、曲库全是客户端自己的事。理解了这一点，音源脚本要做好的其实是三件防线工程：多后端容错、音质阶梯降级、音频真实性校验。文中七个坑全部来自真实建设过程，每个都带排查命令；结尾附 45 组合的实测数据。
📢注意：本文内容为个人学习笔记，仅供参考。附：读者须知
