TidaLuna 插件管理从零开始:LunaStore 插件商店安装、更新与配置完整教程

原创2026-11-14 12:24:231,040 阅读

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)。

📦 四、一键安装插件:从浏览到自动生效

安装流程非常直接:

  1. 在商店中找到目标插件卡片,点击卡片即可 Install;
  2. 安装成功后该卡片会变暗(表示已安装),再次点击可 Uninstall 卸载;
  3. 插件信息(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):

  1. 点击刷新按钮获取全部发布版本;
  2. 在下拉框中选择目标版本;
  3. 点击 Update Client 更新(版本相同时则为 Reinstall 重装);
  4. 按提示重启客户端完成升级。

⚠️ 该区域还有 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 插件管理的从零到精通:

  1. 头像菜单 → Luna Settings 进入设置页;
  2. Plugin Store 中浏览、搜索、添加商店并一键安装;
  3. Plugins 标签中开关、重载、卸载和配置插件;
  4. Settings 标签升级客户端、备份迁移设置。

祝你在 TidaLuna 的插件世界里玩得开心 🎧

登录后查看全文
TidaLuna