Pear Desktop 插件开发实战指南:为 YouTube Music 打造原生级桌面扩展
Pear Desktop 插件开发实战指南:为 YouTube Music 打造原生级桌面扩展
Pear Desktop 是一款面向 YouTube Music 的桌面扩展,其核心价值在于以"原生外观与体验"(Native look & feel)为目标,通过一套结构清晰的插件系统把各类功能(下载、歌词、跨平台信息同步、视觉主题等)挂载到音乐播放器之上。本文以仓库根目录的 README.md 为主线,完整讲解从下载安装、本地开发、插件编写到多平台打包发布的全部流程,并结合仓库源码剖析插件加载器、配置存储与生命周期回调的底层实现,帮助你从"会用插件"进阶到"能写插件、能改插件、能打包自己的版本"。
项目定位与总体架构
从 package.json 可以看到,Pear Desktop 的产品名为 YouTube Music,描述为"YouTube Music Desktop App - including custom plugins",当前版本为 3.12.0,基于 Electron 42、electron-vite 与 pnpm 构建,采用 MIT 协议。它并非 Google 或 YouTube 的官方产品,而是一个由志愿者维护的独立、非营利、非官方扩展项目,README 中对此有明确的免责声明(No Affiliation / Trademarks / Limitation of Liability),使用时请自行承担风险。
从源码结构看,项目的插件体系横跨 Electron 的四个运行环境,每个插件都可以按需提供以下上下文(context):
| 上下文 | 对应源码 | 典型能力 |
|---|---|---|
backend |
src/loader/main.ts | 拿到 BrowserWindow,通过 ipc 与渲染进程通信,运行在主进程 |
preload |
src/loader/preload.ts | 预加载脚本上下文,仅具备 getConfig / setConfig 能力 |
renderer |
src/loader/renderer.ts | 操作页面 DOM、注入样式、调用 ipc.invoke |
menu |
src/loader/menu.ts | 向应用菜单注入自定义菜单项 |
四个上下文的具体类型定义集中在 src/types/contexts.ts 中,其中 BackendContext 额外暴露 window(BrowserWindow)与 ipc 四件套(send / handle / on / removeHandler),RendererContext 则暴露 ipc.send / ipc.invoke / ipc.on / removeAllListeners,这正是插件能"操作应用、改前端"的通道。
各平台安装方式
在发布页可找到各平台最新版本(含便携包与安装器)。README 给出的安装路径覆盖四大平台:
Arch Linux
通过 AUR 安装 pear-desktop 包,AUR 的安装方法参照 Arch 官方 wiki(Arch_User_Repository#Installing_packages 一节)。
Solus
sudo eopkg install pear-desktop
macOS
推荐使用 Homebrew 安装(仓库维护了对应的 cask 定义):
brew install pear-devs/pear/pear-desktop
如果手动安装后启动时报错 "is damaged and can’t be opened.",在终端执行以下命令清除隔离属性即可:
/usr/bin/xattr -cr /Applications/Pear\ Desktop.app
Windows
既可以用 Scoop(extras bucket):
scoop bucket add extras
scoop install extras/pear-desktop
也可以用 Windows 11 官方包管理器 Winget:
winget install pear-devs.pear-desktop
注意:由于发布者未签名,Microsoft Defender SmartScreen 可能会拦截安装(手动下载运行 .exe 时同样如此),属正常现象。
Windows 无网络环境离线安装
- 在发布页下载对应架构的
*.nsis.7z文件:x64(64 位)、ia32(32 位)、arm64(ARM64); - 下载安装器
*-Setup.exe; - 将两者放在同一目录;
- 运行安装器即可。
主题定制(Themes)
Pear Desktop 允许通过加载 CSS 文件改变应用外观,入口在 Options > Visual Tweaks > Themes。仓库中也有多个插件以 style.css 的形式实现视觉定制(例如 src/plugins/blur-nav-bar、src/plugins/transparent-player),可作为主题编写参考。README 还提到社区维护了一批预定义主题可供选用。
本地开发环境搭建
仓库依赖 node >= 22 与 pnpm >= 11(见 package.json 的 engines 字段)。搭建开发环境只需三步:
git clone <仓库地址>
cd pear-desktop
pnpm install --frozen-lockfile
pnpm dev
其中 pnpm install --frozen-lockfile 会严格按照 pnpm-lock.yaml 安装依赖(postinstall 阶段还会自动执行 pnpm install-electron 下载 Electron)。pnpm dev 实际对应 electron-vite dev --watch(见 package.json 的 scripts),支持热更新调试。
如果你不想在宿主机安装 pnpm,也可以使用仓库提供的 devcontainers:在 VS Code 中打开项目后"Reopen in Container",即可在容器内开发或构建。需要留意的是 devcontainer 有一定限制,例如在部分 Linux 宿主机上 GUI 无法工作。
插件系统核心机制
createPlugin:插件定义的入口
插件通过 src/utils/index.ts 导出的 createPlugin 函数定义自身:
export const createPlugin = <BackendProperties, PreloadProperties, RendererProperties, Config extends PluginConfig = PluginConfig>(
def: PluginDef<...> & { config?: Omit<Config, 'enabled'> & { enabled: boolean } },
) => def;
它本质上是一个类型辅助函数——接收插件定义对象并原样返回,同时借助泛型约束保证 config 中必须存在 enabled: boolean(所有插件的开关)。插件的完整结构定义见 src/types/plugins.ts,可配置的顶层字段包括:
name: () => string:插件名(函数形式,便于接入 i18n);authors、description、addedVersion:元信息;config: Config:插件自定义配置,必须以enabled: boolean开头;platform?: Platform:按位掩码限定运行平台(Windows / macOS / Linux / FreeBSD);menu(ctx):返回Electron.MenuItemConstructorOptions[],用于注入菜单;stylesheets: string[]:注入到页面的 CSS 字符串数组;restartNeeded: boolean:为true时,开关插件会弹出重启对话框;backend/preload/renderer:三个环境的生命周期对象。
构建期的上下文裁剪
一个值得注意的工程细节是:插件文件在构建时会被 vite-plugins/plugin-loader.mts 静态分析。该 Vite 插件用 ts-morph 解析每个 src/plugins/<name>/index.ts 的 export default createPlugin({...}),然后按目标环境裁剪不需要的上下文字段:构建 main 时保留 backend 与 menu,构建 preload 时保留 preload,构建 renderer 时保留 renderer,避免把主进程代码带进渲染进程。这意味着同一份插件定义会根据运行环境被编译成三个"瘦身"版本,再由 virtual:plugins 模块统一注入(见 electron.vite.config.mts)。
配置的合并与持久化
插件配置通过 src/config/index.ts 与 src/config/plugins.ts 管理,核心逻辑是 deepmerge:每次读取配置时,插件自带默认值(pluginDef.config)与用户持久化值(config.get('plugins.<id>'))都会被深度合并,用户配置优先;写入时则通过 setPartial 保留默认值与已有值,只更新增量字段。enable / disable 会经由 setMenuOptions 写入配置,并且当全局选项 options.restartOnConfigChanges 开启时会自动触发应用重启。
生命周期回调与加载器
所有上下文的生命周期由 src/utils/index.ts 的 startPlugin / stopPlugin 统一驱动:它们会识别两种写法——"简单函数式"(整个 backend 就是一个函数)与"对象式"({ start, stop, onConfigChange }),并会把 this 绑定到上下文对象上。各环境的加载器(loadAllMainPlugins / loadAllPreloadPlugins / loadAllRendererPlugins)会遍历全部插件,读取合并后的配置,仅对 enabled: true 的插件执行 forceLoad*。渲染进程的样式注入尤其值得一提:stylesheets 会被转换为 CSSStyleSheet 并通过 document.adoptedStyleSheets 生效(见 src/loader/renderer.ts),卸载时则移除对应样式并注销监听。
创建你的第一个插件
在 src/plugins/YOUR-PLUGIN-NAME 下新建插件,核心文件是 index.ts。README 给出了一个同时覆盖四种上下文的完整模板,这里完整保留并逐段讲解:
import style from './style.css?inline'; // import style as inline
import { createPlugin } from '@/utils';
export default createPlugin({
name: 'Plugin Label',
restartNeeded: true, // if value is true, ytmusic show restart dialog
config: {
enabled: false,
}, // your custom config
stylesheets: [style], // your custom style,
menu: async ({ getConfig, setConfig }) => {
// All *Config methods are wrapped Promise<T>
const config = await getConfig();
return [
{
label: 'menu',
submenu: [1, 2, 3].map((value) => ({
label: `value ${value}`,
type: 'radio',
checked: config.value === value,
click() {
setConfig({ value });
},
})),
},
];
},
backend: {
start({ window, ipc }) {
window.maximize();
// you can communicate with renderer plugin
ipc.handle('some-event', () => {
return 'hello';
});
},
// it fired when config changed
onConfigChange(newConfig) { /* ... */ },
// it fired when plugin disabled
stop(context) { /* ... */ },
},
renderer: {
async start(context) {
console.log(await context.ipc.invoke('some-event'));
},
// Only renderer available hook
onPlayerApiReady(api, context) {
// set plugin config easily
context.setConfig({ myConfig: api.getVolume() });
},
onConfigChange(newConfig) { /* ... */ },
stop(_context) { /* ... */ },
},
preload: {
async start({ getConfig }) {
const config = await getConfig();
},
onConfigChange(newConfig) {},
stop(_context) {},
},
});
各字段的实战要点:
name:菜单与日志中展示的插件名,常配合t()做国际化;restartNeeded: true:开启该插件时应用会弹出重启确认对话框,适用于无法热装载的改动;config:插件私有配置,enabled为总开关;menu中的getConfig/setConfig都包装为Promise,所有*Config方法都是异步的;menu:返回 Electron 菜单模板,示例中用type: 'radio'实现单选,checked回读当前配置,click中写入新配置——配合 src/loader/menu.ts 的refresh上下文,菜单变更后可重新构建应用菜单(若启用了 in-app-menu 插件,还会同步刷新应用内菜单);backend.start({ window, ipc }):主进程入口,window是BrowserWindow实例(README 明确指出"插件的 handler 会拿到 Electron 的 BrowserWindow",因此你可以操作窗口本身),ipc.handle可注册供渲染进程调用的处理器;onConfigChange(newConfig):配置变化回调,每个环境都有;stop(context):插件被禁用时触发,用于清理资源;renderer.start(context):渲染进程入口,context.ipc.invoke('some-event')会命中 backend 注册的ipc.handle('some-event'),从而打通"渲染进程 → 主进程"通道;onPlayerApiReady(api, context):渲染进程独有钩子,在播放器 API 就绪时触发,api提供getVolume()等播放控制方法(对应 src/types/music-player.ts 的MusicPlayer接口),可在这里用context.setConfig便捷地把播放器状态写入插件配置;preload.start({ getConfig }):预加载上下文只提供配置读写,适合做轻量的初始化工作。
常见用例(Common Use Cases)
注入自定义 CSS
在同目录创建 style.css,在插件中通过 ?inline 导入并放入 stylesheets:
// index.ts
import style from './style.css?inline'; // import style as inline
import { createPlugin } from '@/utils';
export default createPlugin({
name: 'Plugin Label',
restartNeeded: true, // if value is true, pear-desktop will show a restart dialog
config: {
enabled: false,
}, // your custom config
stylesheets: [style], // your custom style
renderer() {} // define renderer hook
});
?inline 是 Vite 的查询参数语法,会把 CSS 编译为字符串注入 JS 包。渲染进程加载器会将该字符串通过 CSSStyleSheet.replaceSync 解析并挂到 document.adoptedStyleSheets,实现无闪烁的样式注入。
修改页面 HTML
只要定义了 renderer 钩子,就可以在渲染进程自由操作 DOM:
import { createPlugin } from '@/utils';
export default createPlugin({
name: 'Plugin Label',
restartNeeded: true, // if value is true, ytmusic will show the restart dialog
config: {
enabled: false,
}, // your custom config
renderer() {
console.log('hello from renderer');
} // define renderer hook
});
仓库中大量插件都采用这种模式,例如 src/plugins/in-app-menu/renderer.tsx 用 Solid.js 渲染应用内菜单组件,src/plugins/quality-changer 通过模板向页面注入画质切换按钮。
前后端通信
README 指出:前端与后端之间的通信可以使用 Electron 的 ipcMain 模块完成,并推荐参考 sponsorblock 插件的实现。以 src/plugins/sponsorblock/index.ts 为例,它在 backend 中订阅 ipc.on('peard:video-src-changed', ...),每当播放器切换视频源(该事件由页面层在检测到新 GetPlayerResponse 时发出),后端就调用 SponsorBlock API(GET /api/skipSegments?videoID=...&categories=...)拉取可跳过段落并排序,随后把结果推送回渲染进程完成自动跳过。该插件还演示了 config 中自定义 apiURL 与 categories 的用法,配置默认值 apiURL: 'https://sponsor.ajay.app' 与六个可跳过分类(sponsor / intro / outro / interaction / selfpromo / music_offtopic)都直接声明在插件定义里。
构建与分发
构建前确保已安装 pnpm(官方安装指南见 pnpm 文档),然后执行 pnpm install --frozen-lockfile。构建命令由 package.json 的 scripts 定义,统一走 pnpm clean && pnpm build && pnpm electron-builder 链路,基于 electron-builder 产出安装包:
pnpm dist:win- Windowspnpm dist:linux- Linux(amd64)pnpm dist:linux:deb-arm64- Linux(arm64,Debian 系)pnpm dist:linux:rpm-arm64- Linux(arm64,Fedora 系)pnpm dist:mac- macOS(amd64)pnpm dist:mac:arm64- macOS(arm64)
构建产物统一输出到 dist 目录。
在 devcontainer 中构建
- 克隆仓库;
- 用 VS Code 打开文件夹;
- 按提示"Reopen in Container";
- 按需执行上述
pnpm dist:*命令; - 从
dist目录收集构建产物。
由于 devcontainer 对工作区使用挂载,宿主机上同样可以直接拿到构建产物。
生产预览与测试
预览生产构建使用:
pnpm start
对应 electron-vite preview,可在不打包的情况下以接近生产的形态运行应用。调试渲染进程时可用 pnpm start:debug(会开启 ELECTRON_ENABLE_LOGGING)。
测试使用 Playwright 驱动:
pnpm test
即 pnpm playwright test(见 package.json),测试入口在 tests/index.test.js。调试测试可运行 pnpm test:debug,会开启 DEBUG=pw:* 的详细协议日志。
License 与 FAQ
项目以 MIT 协议开源(见 license),版本历史可查阅 changelog.md。
常见问题:为什么应用菜单不显示? 如果开启了 Hide Menu 选项,可以通过 alt 键临时唤出菜单;若启用了 in-app-menu 插件(应用内菜单,实现在 src/plugins/in-app-menu),则改用 `(反引号键)唤出。
小结
围绕 README.md 的脉络,可以看到 Pear Desktop 的工程化设计贯穿始终:createPlugin + 类型系统约束插件契约,deepmerge 统一默认值与用户配置,四个上下文加载器在 Electron 主/预加载/渲染进程中各司其职,构建期 Vite 插件按环境裁剪插件体积,最终通过 electron-builder 一键产出全平台安装包。对开发者而言,最快的学习路径是:先运行 pnpm dev 熟悉应用,再对照 sponsorblock 等内置插件理解 IPC 与生命周期,最后用本文的完整模板写出自己的第一个插件。