ytmdesktop（YouTube Music Desktop App）实战指南：从下载安装到开发构建的完整流程

• 桌面应用
• 音频

ytmdesktop（仓库名ytmdesktop，产品名 "YouTube Music Desktop App"）是一款基于 Electron 的 YouTube Music 桌面客户端，当前仓库已演进为v2 全新代码库。本文以仓库 README.md 为主线，结合 package.json、forge.config.ts 与 src/main/index.ts 等源码，系统讲解各平台下载安装、本地开发环境搭建、yarn make打包构建的完整链路，并补充源码级的架构与配置佐证。读完本文，你将能够在本机快速运行 v2 版本，并在 Windows / Linux 上产出可分发安装包。

一、项目概览：一个全新的 v2 代码库

仓库当前版本为2.0.12（见 package.json），README 以 "Now with a Fresh new Codebase" 强调这是一个与 v1 完全不同的重构实现。它不再是把 YouTube Music 网页简单包进 WebView，而是构建了一套**主进程（Main）— 渲染进程（Renderer）— 音乐视图（YTM View）**三层的 Electron 应用：

• 主进程入口 src/main/index.ts：负责窗口管理、托盘、全局快捷键、状态存储、自动更新与各集成模块的启停；
• 渲染进程位于 src/renderer：包含主窗口、设置窗口、授权窗口三个 Vue 3 页面，以及注入 YouTube Music 页面的 ytmview/preload.ts；
• 技术栈从 package.json 可见：Electron^44.3.0+ Electron Forge~7.11.1+ Vite^5.4.21+ Vue^3.5.28+ TypeScript，配套 Fastify / Socket.IO / conf 等运行时依赖。

二、各平台下载与安装

README 为三大桌面平台分别列出了官方与社区维护的安装途径。以下命令均取自 README.md。

Windows

• Winget（官方维护入口之一）：

  winget install "YouTube Music Desktop App"

  或使用包 ID：

  winget install Ytmdesktop.Ytmdesktop

• Scoop（社区维护，需要先添加 extras bucket）：

  scoop bucket add extras scoop install ytmdesktop

• 二进制安装包：从项目 Releases 页面下载安装器（Windows 侧安装包由 Electron Forge 的MakerSquirrel生成，见下文构建章节）。

Linux

• Arch Linux（AUR）（社区维护）：

  # AUR 包名：ytmdesktop，可通过 yay / paru 等 AUR Helper 安装

• 二进制安装包：Releases 页面同时提供.deb与.rpm包，分别由MakerDeb与MakerRpm产出。

macOS

• Homebrew（社区维护）：

  brew install --cask ytmdesktop-youtube-music

• 二进制安装包：从 Releases 页面下载（darwin 平台由MakerZIP产出 zip 包，见 forge.config.ts）。

注意：README 明确指出 Scoop（Windows）、AUR（Linux）、Homebrew（macOS）三条渠道均为社区维护，而 Winget 与官方二进制由项目自身发布，安装时请以各自仓库的最新说明为准。

三、本地开发：从克隆到yarn start

环境要求

README 明确要求本机预先安装：

• Git（用于克隆仓库）；
• Node.js v20（自带 npm）。README 原文指定 v20，仓库声明的包管理器为yarn@4.5.1（见 package.json）。

克隆与安装

# 克隆本仓库（GitCode 镜像） git clone https://gitcode.com/gh_mirrors/yt/ytmdesktop.git cd ytmdesktop

若尚未安装 Yarn，或对 Node 生态不熟悉，可通过 corepack 启用（README 官方推荐路径）：

corepack enable

随后安装依赖并启动开发模式：

# 安装依赖 yarn install # 运行应用 yarn start

yarn start实际执行的是electron-forge start（见 package.json），由 Forge 的 Vite 插件并行构建主进程与各 preload 脚本，并拉起 Vite Dev Server 提供渲染页面。开发模式下应用会自动打开 DevTools。

源码级佐证：启动时发生了什么

从 src/main/index.ts 可以看到应用启动的关键链路：

• app.enableSandbox()对所有渲染进程强制沙箱；
• 通过app.requestSingleInstanceLock()保证单实例，收到second-instance事件时唤起已有窗口并处理协议 URL（src/main/index.ts）；
• 注册自定义协议ytmd，支持ytmd://play/{videoId}/{playlistId}形式的深链控制（src/main/index.ts）；
• app.on("ready")中完成首次运行检测、v1 配置迁移询问、权限处理器注册、托盘创建、主窗口与 YTM 视图创建（src/main/index.ts）。

四、源码架构速览：三层结构与数据流

为便于后续修改源码，这里结合仓库结构给出核心脉络（均为 v2 实际实现，路径真实存在）：

关键数据流：ytmview/preload.ts通过contextBridge.exposeInMainWorld("ytmd", ...)暴露sendVideoProgress / sendVideoState / sendVideoData / sendStoreUpdate等桥接方法（src/renderer/ytmview/preload.ts），主进程对应在 src/main/index.ts 中监听ytmView:videoProgressChanged、ytmView:videoStateChanged等 IPC 事件，统一写入 src/main/player-state-store/index.ts 维护的PlayerStateStore，再分发给任务栏按钮、托盘菜单、通知与各集成模块。

持久化配置：conf 存储

应用使用conf保存设置（src/main/index.ts），默认值定义在 src/shared/store/schema.ts，配置文件名为config，存放于app.getPath("userData")。主要配置分组：

应用还内置了从 v2.0.0 到 v2.0.7 的存储迁移逻辑（src/main/index.ts），并在首次启动时检测 v1 遗留的config.json，弹窗询问是否迁移旧设置（src/main/index.ts）。

全局快捷键与托盘

registerShortcuts()（src/main/index.ts）通过globalShortcut注册 7 个可选快捷键：playPause、next、previous、thumbsUp、thumbsDown、volumeUp、volumeDown，全部经remoteControl:execute转发到 YTM 视图；托盘菜单（src/main/index.ts）同样提供 Show/Hide、Play/Pause、Previous、Next、Quit 操作，并在 Windows 任务栏上动态更新缩略图按钮与播放/暂停图标。

五、打包构建：yarn make全流程

README 说明：构建对应平台安装包只需执行yarn make（即electron-forge make，见 package.json），但不同平台需要额外安装构建工具。

Windows

官方推荐直接安装 Electron 官方提供的构建工具套件（内含 Visual Studio、Python 及其他工具）：

npm i -g @electron/build-tools

安装过程会持续下载并可能出现若干交互提示，完成后即可执行yarn make产出 Squirrel 安装器。

Linux

Debian 系发行版（如 Ubuntu）需要：

• fakeroot
• dpkg

RedHat 系发行版（如 Fedora）需要：

• rpm或rpm-build

README 特别提醒：在 Linux 发行版上执行构建时，默认会同时构建两种包（.deb与.rpm），这一点与 forge.config.ts 中同时注册MakerDeb与MakerRpm的实现一致。

构建配置要点（源码佐证）

forge.config.ts 是 Forge 构建的权威配置，包含：

• 打包器：可执行名youtube-music-desktop-app、应用图标src/assets/icons/ytmd、随包携带托盘与播放控制图标资源（forge.config.ts）；
• 自定义协议：注册ytmdscheme（mimeType: ["x-scheme-handler/ytmd"]用于 Linux 包，见 forge.config.ts）；
• Vite 插件：五个构建目标——主进程入口 src/main/index.ts、主窗口/settings/authorize-companion/ytmview 四个 preload（forge.config.ts）；
• Fuses 安全加固：禁用RunAsNode、启用 Cookie 加密、关闭 Node 环境变量与 CLI inspect、开启 ASAR 完整性校验与"仅从 ASAR 加载应用"（forge.config.ts）；
• 发布器：通过@electron-forge/publisher-github发布到 GitHub Releases，仓库名可通过YTMD_UPDATE_FEED_OWNER/YTMD_UPDATE_FEED_REPOSITORY环境变量覆盖（forge.config.ts）。

自动更新机制

更新逻辑集中在 src/main/index.ts：shouldDisableUpdates()表明当前仅 Windows 启用自动更新——macOS 缺少代码签名无法使用autoUpdater，Linux 的更新服务器不受支持。打包且未通过YTMD_DISABLE_UPDATES禁用时，应用每 15 分钟向update.electronjs.org拉取一次更新源，下载完成后自动quitAndInstall()。

六、可扩展生态：内置集成模块

v2 把功能拆分为独立集成模块（统一实现 integration.ts 的provide / enable / disable / getYTMScripts接口），目录见 src/main/integrations：

各模块的启用/禁用均由 src/main/index.ts 中store.onDidAnyChange统一调度，例如启用companionServerEnabled会先provide()再enable()。

Companion Server：可编程控制接口

这是面向开发者的核心扩展点，服务默认监听0.0.0.0:9863（companion-server/index.ts），启用前提是系统safeStorage可用（用于加密存储授权 Token）。根路径/metadata返回{ apiVersions: ["v1"] }。v1 API 端点（实现见 api/v1/index.ts）：

/api/v1/command支持的命令（schema 定义在 api-shared/schemas.ts）：playPause、play、pause、volumeUp、volumeDown、setVolume（0–100）、mute、unmute、seekTo、next、previous、repeatMode（NONE/ALL/ONE）、shuffle、playQueueIndex、changeVideo（videoId/playlistId）、toggleLike、toggleDislike。所有命令通过remoteControl:execute转发到 YTM 视图执行；/api/v1/state与实时事件中的player/video/playlistId字段由transformPlayerState从PlayerStateStore映射而来（api/v1/index.ts）。授权 Token 结构见 shared/integrations/companion-server/types.ts。

七、许可与贡献

• 许可证：仓库采用GPL-3.0-only（见 package.json 与 LICENSE），二次分发需遵守 GPL-3.0 相关义务。
• 贡献者：README 对全部历史贡献者致谢，仓库还提供了 scripts/generateContributors.mjs 脚本用于自动生成贡献者名单。
• 开发规范：yarn lint（ESLint + Vue 插件）、yarn prettier（Prettier 校验），并在postinstall阶段自动启用 Husky（见 package.json），lint-staged 会在提交时对*.{ts,tsx,vue}自动执行 prettier 与 eslint 修复。

八、常见注意事项

• 开发环境版本：README 指定 Node.js v20 + Yarn（corepack enable激活）；仓库依赖锁文件为yarn.lock，推荐使用 Yarn 安装而非 npm。
• Linux 构建默认双包：执行yarn make会同时产出 deb 与 rpm，请确保两类工具链齐备，或按需调整 forge.config.ts 的 maker 列表。
• 自动更新仅限 Windows：Linux 与 macOS 打包版不会从更新服务器拉取新版本，升级需手动下载安装包。
• 首次启动迁移：若检测到 v1 的config.json，应用会弹窗询问是否迁移（部分旧设置如 Last.fm 账号需重新授权），迁移实现见 src/main/index.ts。

以上流程覆盖了从最终用户下载、开发者本地运行到跨平台打包的完整闭环。若需深入某一模块（如 Companion Server 的命令语义、播放器状态映射），可继续在仓库内阅读对应源码与类型定义。

• 桌面应用
• 音频