Pear Desktop 插件开发实战指南:为 YouTube Music 打造原生级桌面扩展

原创2026-09-29 13:42:371,898 阅读
文章标签:桌面应用插件系统音视频跨平台

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 无网络环境离线安装

  1. 在发布页下载对应架构的 *.nsis.7z 文件:x64(64 位)、ia32(32 位)、arm64(ARM64);
  2. 下载安装器 *-Setup.exe;
  3. 将两者放在同一目录;
  4. 运行安装器即可。

主题定制(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 - Windows
  • pnpm 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 中构建

  1. 克隆仓库;
  2. 用 VS Code 打开文件夹;
  3. 按提示"Reopen in Container";
  4. 按需执行上述 pnpm dist:* 命令;
  5. 从 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 与生命周期,最后用本文的完整模板写出自己的第一个插件。

登录后查看全文
pear-desktop