Pear Desktop：音乐播放器桌面客户端

项目简介

Pear Desktop 是一个基于 Electron 构建的桌面音乐播放器客户端，以浏览器扩展的形式为音乐播放器网页版带来原生的桌面外观与操作体验。项目使用 TypeScript 编写，采用 MIT 许可证开源，由志愿者团队独立开发，提供 Windows、macOS 与 Linux 版本。

主要功能

• 原生外观与操作体验：将音乐播放器网页版封装为独立桌面应用。
• 主题自定义：可加载 CSS 文件改变应用外观（选项 > Visual Tweaks > Themes）。
• 插件机制：通过插件干预应用行为或修改前端 HTML/CSS。
  • 可操作 Electron 的 BrowserWindow；
  • 可注入自定义样式与页面修改；
  • 前后端可通过 Electron 的 ipcMain 模块通信。
• 多语言翻译：项目在 Weblate 上接受翻译贡献。

安装与使用

可从 latest release 页面下载最新版本。

Arch Linux

从 AUR 安装 pear-desktop 包，安装方法参见 Arch Wiki。

Solus

sudo eopkg install pear-desktop

macOS

使用 Homebrew 安装（cask 定义见 homebrew-pear）：

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 安装 pear-devs.pear-desktop：

winget install pear-devs.pear-desktop

无网络环境下安装（Windows）

• 在 release 页面 下载对应设备架构的 *.nsis.7z 文件：x64（64 位）、ia32（32 位）、arm64（ARM64）。
• 在同一页面下载安装程序（*-Setup.exe）。
• 将两者放在同一目录下，运行安装程序。

主题

在「选项 > Visual Tweaks > Themes」中加载 CSS 文件即可更换外观，部分预设主题见 https://github.com/kerichdev/themes-for-ytmdesktop-player 。

本地开发

git clone https://github.com/pear-devs/pear-desktop
cd pear-desktop
pnpm install --frozen-lockfile
pnpm dev

也可以使用 devcontainers 作为开发环境或在未安装依赖的情况下构建项目（注意：在部分 Linux 宿主机上 GUI 无法工作）。

构建

1. 克隆仓库；
2. 参照 指南 安装 pnpm；
3. 运行 pnpm install --frozen-lockfile 安装依赖；
4. 运行 pnpm build:OS：

pnpm dist:win          # Windows
pnpm dist:linux        # Linux (amd64)
pnpm dist:linux:deb-arm64  # Linux (Debian arm64)
pnpm dist:linux:rpm-arm64  # Linux (Fedora arm64)
pnpm dist:mac          # macOS (amd64)
pnpm dist:mac:arm64    # macOS (arm64)

构建由 electron-builder 完成。生产预览使用 pnpm start，测试使用 pnpm test（基于 Playwright）。

编写插件

在 src/plugins/YOUR-PLUGIN-NAME 下创建插件文件夹，其中 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, 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) {},
  },
});

常见用法是注入自定义 CSS（在同目录创建 style.css 并以 ?inline 方式引入，通过 stylesheets 传入）；前后端通信可参考 sponsorblock 插件。

注意事项

• 非官方项目：本项目及其贡献者与 Google LLC、YouTube 及其子公司或关联公司没有任何隶属、授权、认可或官方关联，是志愿者团队开发的独立、非营利、非官方扩展。
• 商标：“Google”“YouTube Music”等相关名称、标识、徽章和图像均为其各自所有者的注册商标，此处仅用于识别与说明。
• 免责声明：本应用按“AS IS”提供，使用风险由用户自行承担；开发者与贡献者不对因使用本软件产生的任何索赔、损害或其他责任（包括法律后果）负责。
• Windows 上 Microsoft Defender SmartScreen 可能因“未知发布者”阻止安装，手动下载运行 .exe 时同样如此。
• 若应用菜单不显示，可能是开启了 Hide Menu 选项，可按 <kbd>alt</kbd> 键（使用 in-app-menu 插件时按 <kbd>`</kbd> 反引号）显示菜单。

---

本作品整理自 GitHub 开源项目 pear-devs/pear-desktop，原作者 @pear-devs，许可证 MIT。中文介绍由 AI 根据项目 README 整理，以原仓库为准。