TidaLuna 插件管理从零开始:LunaStore 插件商店安装、更新与配置完整教程
TidaLuna 插件管理从零开始:LunaStore 插件商店安装、更新与配置完整教程
TidaLuna 是 Tidal 音乐客户端的官方社区 mod(Neptune 的继任者),支持通过插件修改和增强客户端功能。本文面向新手,讲解 TidaLuna 插件管理的完整流程:如何打开设置页、在 LunaStore 插件商店中一键安装插件、更新与重载插件,以及配置、备份插件设置,让你零基础也能快速上手。
🚀 一、TidaLuna 是什么?为什么需要插件管理
TidaLuna 是一个注入 Tidal 客户端的改造框架,核心能力就是让开发者创建插件、让用户安装和运行插件,从而扩展 Tidal 的功能(详见 README.md)。
插件管理集中在 Luna Settings 设置页中,覆盖四大场景:
- 🏪 安装:从 LunaStore 插件商店浏览并一键安装插件
- 🔁 更新:重载插件获取最新版本,升级客户端本体
- ⚙️ 配置:开关插件、展开插件自定义设置面板
- 💾 迁移:一键导出/导入插件列表与全部设置
🧭 二、3步进入插件管理入口(打开 Luna 设置页)
第 1 步:在 Tidal 中点击用户头像,会弹出上下文菜单;
第 2 步:选择菜单中的 Luna Settings 按钮(该入口由 plugins/ui/src/index.tsx 注册到 USER_PROFILE 菜单中);
第 3 步:进入设置页后,你会看到 5 个标签页(见 plugins/ui/src/SettingsPage/index.tsx):
| 标签 | 用途 |
|---|---|
| Plugins | 管理已安装的插件(开关、重载、卸载、配置) |
| Plugin Store | LunaStore 插件商店,浏览和安装新插件 |
| Themes | 主题外观 |
| Settings | 客户端更新、设置迁移等 |
| Supporters | 项目支持者 |
💡 小提示:设置页还支持
tidaluna://深链,可以直接跳到 Plugin Store 或 Plugins 标签(见 plugins/ui/src/index.tsx)。
🏪 三、认识 LunaStore 插件商店:浏览、搜索与添加商店
打开 Plugin Store 标签,核心功能都在一个页面里(源码:plugins/ui/src/SettingsPage/PluginStoreTab/index.tsx):
- 默认商店已内置:TidaLuna 出厂自带多个社区插件商店,打开即自动加载,每个商店会显示名称、作者和描述;
- 搜索框(Search plugins...):按插件名实时过滤,跨所有商店检索;
- Install from URL 输入框:粘贴以
/store.json结尾的地址可添加新商店,直接粘贴插件地址则立即加载该插件(实现见 InstallFromUrl.tsx); - 商店卡片按钮:刷新按钮可重新拉取商店列表,垃圾桶按钮可移除整个商店(逻辑见 LunaStore.tsx)。
每个商店下的插件以卡片网格呈现,鼠标悬停卡片会显示大大的 Install 或 Uninstall 提示(见 LunaStorePlugin.tsx)。
📦 四、一键安装插件:从浏览到自动生效
安装流程非常直接:
- 在商店中找到目标插件卡片,点击卡片即可 Install;
- 安装成功后该卡片会变暗(表示已安装),再次点击可 Uninstall 卸载;
- 插件信息(URL、版本、启用状态)会自动持久化,重启客户端后自动加载,无需重复安装。
背后机制:安装时会把插件写入持久化存储并立即启用,同时自动替换同名旧版本(例如从商店版切换到本地开发版),逻辑位于 render/src/LunaPlugin.ts。
⚠️ 注意:如果同名插件在两个商店中都存在,TidaLuna 会优先保留已安装版本,避免冲突。
🔁 五、插件更新与客户端升级:两步保持最新
1. 更新单个插件(Plugins 标签)
进入 Plugins 标签,每个已安装插件卡片右侧有一组按钮(见 LunaPluginSettings.tsx):
- 重载按钮(Reload plugin):重新拉取插件包,通过 hash 比对代码是否变化,有更新则自动加载新版本;
- 开关(Enable/Disable):临时停用插件而无需卸载;
- LiveReload 按钮:开启后每秒自动检查并热加载代码,主要面向插件开发者调试(见 LiveReloadToggle.tsx);
- 垃圾桶按钮:彻底卸载插件并清除其存储记录。
2. 升级 TidaLuna 客户端本体
打开 Settings 标签,找到 Client Updates 区域(见 LunaClientUpdate.tsx):
- 点击刷新按钮获取全部发布版本;
- 在下拉框中选择目标版本;
- 点击 Update Client 更新(版本相同时则为 Reinstall 重装);
- 按提示重启客户端完成升级。
⚠️ 该区域还有 Factory Reset 按钮,会删除所有插件和配置恢复干净安装,务必三思!
⚙️ 六、插件配置:自定义设置面板与故障排查
展开插件设置:如果插件导出了自定义 Settings 组件,卡片下方会自动显示其设置面板;点击卡片右侧的 ⚙️ 按钮可隐藏/显示设置区,方便在多个插件间快速切换。
常见问题速查:
| 现象 | 原因与处理 |
|---|---|
| 红色发光边框 + 错误文本 | 插件加载失败,点击重载按钮或检查网络后重试 |
| 设置区显示 "Settings crashed" + Retry | 插件设置界面崩溃,点击 Retry 重试即可(见 LunaPluginSettings.tsx) |
| 商店卡片红色描边 | 商店 store.json 拉取失败,点击刷新按钮重试 |
| 没有开关/卸载按钮 | 核心插件(如 @luna/lib、@luna/ui)不允许禁用或卸载,属正常行为 |
| Plugins 页显示 "You have no plugins installed!" | 尚未安装任何插件,去 Plugin Store 逛逛吧 |
💾 七、插件备份与迁移:一键导出导入设置
换机或重装后,用 Settings 标签中的 Settings Transfer 功能迁移全部环境(见 LunaSettingsTransfer.tsx):
- Export Settings:导出已安装插件、插件设置、主题、商店地址和特性开关,生成 JSON 文件;
- Include plugin source code:勾选后可把开发中/未发布的插件源码一并打包;
- Import Settings:选择导出的 JSON 文件,确认后现有设置会被清空并替换,随后自动重启客户端生效。
🎓 八、写在最后
掌握以上流程,你就完成了 TidaLuna 插件管理的从零到精通:
- 头像菜单 → Luna Settings 进入设置页;
- Plugin Store 中浏览、搜索、添加商店并一键安装;
- Plugins 标签中开关、重载、卸载和配置插件;
- Settings 标签升级客户端、备份迁移设置。
祝你在 TidaLuna 的插件世界里玩得开心 🎧