如果你和我一样平时主要靠终端管理 macOS 上的软件包每天在 Homebrew 里敲brew update、brew list、brew upgrade但又总觉得命令行不够直观——尤其是刚接触命令行不久的朋友看到一串brew leaves和依赖关系图就头大。这就是我最初想做 BrewUI 的原因给自己也给身边那些被 CLI 劝退的人做一个能看得见、点得动的 Homebrew 图形界面。BrewUI 本质上是一个围绕 Homebrew 的跨平台桌面工具核心能力包括展示已安装的 formula 和 cask、查看包依赖关系、执行安装/卸载/升级操作、清理旧版本和缓存。对于每天要与几十个包打交道的开发者和 macOS 重度用户来说它把那些需要死记的参数和不断翻文档的命令收拢成一个可视化的操作面板。这篇文章会从设计思路、核心模块、关键代码到实战踩坑完整复盘 BrewUI 的搭建过程如果你也想给自己的常用工具链做一个“看得见的外壳”可以直接拿这套思路往任何命令行工具上套。1. 为什么需要 BrewUI打包管理从“记参数”变成“看界面”1.1 命令行很好用但我承认它对新人不友好Homebrew 的能力确实强brew一条命令能解决依赖解析、下载、链接、版本切换一堆问题。但问题也在这里它把几乎所有能力都暴露给命令行而命令行对不常接触终端的人来说有天然的门槛。brew info的输出密密麻麻brew deps --tree的依赖树一长串更别提brew update和brew upgrade执行时那些白字蓝字的刷屏。我最初动手写 BrewUI就是发现团队里有同事用了几个月 Homebrew仍然只会install和uninstall想更新某个包前先 Google 半天。他们也试过商用工具和网上的管理面板但要么功能太少要么不贴合 Homebrew 的安装习惯要么需要额外起一个后台服务。我很确定在维护日常开发环境这件事上“可视化管理”比“记忆命令”更能减少心智负担。所以 BrewUI 的定位就很明确了它不是一个包管理器而是包管理器前面的一层可视化操作界面真正干活的还是 Homebrew 本身。这个定位决定了项目的核心思路BrewUI 要解决的问题不是“重新实现包管理”而是“让别人更容易使用包管理”。于是所有功能都围绕“展示状态”和“调起命令”两个方向展开前者负责把 Homebrew 的内部信息变成人能看懂的结构后者负责把人的点击翻译成 Homebrew 能执行的命令。这样一来无论 Homebrew 底层逻辑怎么变只要它的命令行接口还在BrewUI 的维护成本就相对可控。1.2 技术选型Electron 还是 Tauri我最后为什么选了 Electron桌面 GUI 有挺多方案我一开始列了三个纯 Electron、Tauri、以及一个偏轻量的方案——用 Python Qt。Python Qt 率先被排除因为要让用户看到漂亮的依赖图和流畅的列表滚动Web 技术栈的开发速度明显更快而且团队里 TypeScript 的经验更足。剩下就是 Electron 和 Tauri 的选择。Tauri 的优势是打包体积小、内存占用低用系统 WebView 渲染前端Rust 做后端。但有一个现实问题BrewUI 的主场景是频繁调用brew命令需要大量的子进程操作和流式输出解析。在 Tauri 里做这些也没问题不过当时 Tauri 的进程管理和 shell 插件还没有现在这么成熟我评估过之后觉得风险偏高。Electron 这边Node.js 的child_process生态非常完整execa、pidtree这些库可以直接用主进程和渲染进程之间的 IPC 也足够稳定。所以最后选择了 Electron Vite React。Electron 负责主进程、子进程调度和窗口管理React 负责界面Vite 负责开发热更新和构建打包。这套组合在今天看来依然很常规但对 BrewUI 这种工具型应用来说“常规”恰恰意味着少踩坑、好维护。提示如果你以后也想做类似工具选型时可以优先看“你熟悉的命令行语言的调用生态是否成熟”而不是单纯追求新技术。包管理类工具的核心是进程调用和输出解析这一层的稳定性比界面框架的噱头重要得多。2. 核心功能拆解BrewUI 做对了哪几件事2.1 包列表与状态同步区分 formula 和 caskHomebrew 里有两类安装对象formula 是命令行工具和库比如git、pythoncask 是图形化应用安装包比如google-chrome、visual-studio-code。这两种包的管理命令虽然都是brew install但展示方式、更新策略、卸载行为差异很大。BrewUI 的包列表不能把两者混在一起展示否则用户会看到一大串不认识的库名里混着几个 App寻找成本很高。我的做法是在列表页加一个 Tab 切换“命令行工具”和“图形应用”。切换时分别调用brew list --formula --json和brew list --cask --json拿到两个独立的数组。每个包卡片展示名称、当前版本、简介、安装路径和体积。状态方面brew 本身不提供“可更新列表”的常驻接口需要执行brew outdated --json才能拿到有新版可用的包所以 BrewUI 把“刷新状态”做成了一个统一的按钮点击后先跑brew outdated再刷新当前可见列表。这里有个细节值得说一下brew list默认返回很快但brew outdated因为要访问远程仓库通常要跑几秒到几十秒。如果每次启动都自动执行用户会明显感觉到卡顿。我在第一版里就栽过这个跟头后来改成“启动时只加载本地列表用户手动触发检查更新”或者提供一个可配置的自动刷新间隔默认 30 分钟。工具类应用最忌讳让用户等一个结果出来才能动能异步就异步能手动触发就不自动抢时间。2.2 安装、卸载与更新的命令封装把 brew 参数变成按钮BrewUI 的第二类核心功能是执行操作。安装、卸载、更新、清理这些操作本质上是给brew传递不同的子命令和参数。难的不是执行命令而是处理好“命令执行中”“执行成功”“执行失败”三种状态并且把输出变成用户可以理解的信息。以安装为例用户点击“安装”后前端调用主进程的runBrewCommand方法传入install、包名、--formula或--cask标记。主进程用execa执行并把 stdout 和 stderr 以流的方式实时回传到渲染进程。这样界面上可以显示一个滚动日志区域用户能看到下载进度和最终安装结果。安装结束后再触发一次“刷新状态”让列表里的新包出现。升级操作要稍微复杂一点因为brew upgrade后面可以接包名也可以不接。不接会升级所有可更新的包原则上很省事但实际使用中用户可能只希望升级某个包因为批量升级容易引入兼容性问题。所以 BrewUI 的默认设计是在“可更新”列表里每个包旁边放一个“升级”按钮同时在顶部保留一个“全部升级”的次要按钮以免用户误操作。这种细节看起来不起眼但决定了工具是“让人放心用”还是“让人担心点错”。2.3 依赖关系可视化把 brew deps 变成一棵看得懂的树依赖图是 BrewUI 最受好评的功能。brew deps --tree在终端里展示的是缩进文本包一多根本看不出来结构。BrewUI 把它变成了一棵可以展开和折叠的树形图。实现原理不复杂brew deps --json会输出一个包名到其直接依赖列表的映射关系。我拿到这个映射后从前台输入一个根包名比如ffmpeg递归查找它的依赖、依赖的依赖构建成一棵嵌套树。这里有个必须处理的坑依赖关系里可能存在循环引用比如 A 依赖 BB 又依赖 A如果不对节点做去重和访问标记递归会陷入死循环。我引入了一个visited集合每次遍历前先检查节点是否处理过处理过的直接返回一个引用占位符同时在 UI 上标注“已展示过”。最终渲染用的是 React 树组件可以按需展开和收起子树。考虑到有些包的依赖层级很深默认只展开两层更多层级延迟加载。真实使用下来这个功能比包列表更直观地回答了“这个包到底依赖了些什么”的问题也是 BrewUI 从“套壳列表”变成“真正有用工具”的关键点。3. 从零实现 BrewUI关键代码实录3.1 环境搭建与工程初始化BrewUI 基于 Electron Vite React项目结构分为主进程和渲染进程两部分。我使用electron-vite这个脚手架来统一管理它比手动配置 Webpack 或 Vite Electron 双进程省心很多。初始化命令npm create quick-start/electronlatest brewui -- --template react-ts cd brewui npm install装完依赖后的目录结构大概是这样的src/main主进程代码负责窗口创建、IPC 通信、子进程调用src/preload预加载脚本用contextBridge暴露安全接口给渲染进程src/rendererReact 界面代码electron-builder.yml打包配置开发阶段运行npm run devVite 会启动渲染进程的本地服务Electron 再加载这个地址。生产构建时npm run build会把渲染进程打包成静态文件由 Electron 直接加载。这个流程如今已经很成熟我建议你第一次做的时候直接沿用这套模板别从零搭配置。3.2 数据访问层用 JSON 和 brew 对话BrewUI 的所有数据都来自 Homebrew 的命令行输出。为了保证解析稳定我尽量让 brew 输出 JSON 格式而不是解析文本。Homebrew 对大部分常用命令都内置了--json参数brew info --jsonv2 --formula git brew list --formula --jsonv2 brew outdated --jsonv2 brew deps --json --formula ffmpeg这样拿到的就是结构化数据解析起来远比文本可靠。我在主进程里写了一个统一的命令执行模块用execa执行命令并返回解析后的 JSON// src/main/brew.ts import { execa } from execa; export async function runBrewJson(args: string[]) { const { stdout } await execa(brew, args, { env: { ...process.env, HOMEBREW_NO_AUTO_UPDATE: 1 }, }); return JSON.parse(stdout); } export async function getInstalledFormula() { return runBrewJson([list, --formula, --jsonv2]); } export async function getOutdated() { return runBrewJson([outdated, --jsonv2]); } export async function getDeps(fullName: string) { return runBrewJson([deps, --json, --formula, fullName]); }这里有一个关键环境变量HOMEBREW_NO_AUTO_UPDATE1。Homebrew 在跑很多命令之前可能会自动git pull更新自身这在交互式终端里问题不大但在 GUI 工具里会拖慢命令响应事件甚至因为网络问题卡很久。设置这个环境变量之后brew 会跳过自动更新让命令执行速度明显提升。代价是它会输出一条提示信息但--json模式下的正式输出并不受影响。再说execa这个库。Node.js 原生也有child_process.exec和spawn但execa的 API 更友好支持 promise 封装、流式输出、超时控制。它内部已经把 stdout 和 stderr 做了收流对常见情况处理得非常好。在只拿 JSON 的场景直接await即可。3.3 前端界面与交互设计别让用户等白屏前端部分我用了 React 和 Ant Design 的组件库因为表格、按钮、消息提示这些基础组件可以省很多事。包列表直接用 Table依赖树用 Tree操作反馈用 message。状态管理没有引入 Redux 这类重库只在 React 组件内部用useReducer管理“加载中”“成功”“失败”三种状态栈因为 BrewUI 的状态其实不复杂一个包列表、一个更新列表、一个正在执行命令的队列。执行命令时的防重复操作非常关键。比如用户连续点击两次“安装”可能会拉起两个 brew 进程互相抢锁。这个问题一度让我很头疼。brew 自己有一个锁机制在同一时刻只能有一个写操作执行第二个命令会等很久甚至直接失败。所以 BrewUI 在前端做了“按钮级 loading”点击后按钮变为 loading 状态禁用所有影响同一包的操作等命令执行完再恢复。更进一步我在主进程里维护了一个全局任务队列同一个时间只允许一个 brew 写操作执行其余进入等待队列// src/main/queue.ts let running false; const queue: Array() void []; export async function enqueueBrewTaskT(task: () PromiseT): PromiseT { return new Promise((resolve, reject) { queue.push(async () { try { const result await task(); resolve(result); } catch (error) { reject(error); } }); processQueue(); }); } async function processQueue() { if (running) return; running true; while (queue.length 0) { const task queue.shift(); if (task) await task(); } running false; }这个队列避免了多个写操作同时执行导致的锁等待问题也让界面上“当前有几个操作排队中”的提示变得很简单queue.length 就是排队数量。命令执行的日志展示我采用的是“实时回传 滚动到底部”的方式。主进程用execa的stdio: [inherit, pipe, pipe]拿到流再通过webContents.send(command-log, chunk)把每一段输出推给渲染进程。渲染进程收集到日志数组后用ref控制容器在每次内容更新后滚动到底部。这里注意不要用innerHTML直接插入日志文本因为命令输出可能包含特殊字符直接用文本节点设置更安全。3.4 打包与分发从开发到可安装开发完成后接入打包流程。Electron 应用打包用electron-builderBrewUI 的打包目标是 macOS 上的 dmg 和 zip。配置里有几个关键点files字段要包含dist目录和主进程代码不要把所有源码都打进去。macOS 签名和公证需要开发者证书我没有单独买开发者账号所以本地测试时用的是跳过签名的配置真机验证通过后再走签名流程。这个过程有点麻烦但 App Store 外的 macOS 应用不签名很难运行在配置里加MACOS_SKIP_SIGNING环境变量可以暂时跳过。因为 brew 命令在打包后的应用里依然可用所以运行时依赖的就是系统里真实的 Homebrew不需要把 brew 一起打包。# electron-builder.yml appId: com.example.brewui productName: BrewUI directories: output: release files: - out/** - package.json mac: target: - dmg - zip category: public.app-category.developer-tools打包完成后 dmg 大概几十 MB对 Electron 应用来说已经算小了。安装后第一次启动BrewUI 会自动检测系统是否安装了 Homebrew如果没有安装会引导用户去官网执行安装命令而不是在 GUI 内部尝试安装。这个设计很保守但避免了权限和环境变量一堆问题。4. 常见问题与排查技巧实录4.1 brew 输出格式变化导致解析失败Homebrew 的更新频率很高命令行输出的格式偶尔会变。BrewUI 最严重的一次事故是brew list --jsonv2输出的字段名从versions变成了installed_versions之类的调整导致前端拿不到版本号。排查这个问题的方式是在主进程里加一个“原始输出查看”功能界面上可以一键复制最后一次命令的原始 stdout。这样当用户反馈“版本没显示”时我可以先看原始 JSON判断是 brew 改了格式还是代码解析问题。后续为了降低这类问题的发生率我在解析 JSON 时用了解构赋值加默认值const version item.versions?.stable ?? unknown;这样即使字段缺失界面也不会直接崩溃。4.2 子进程卡死与超时brew 某些命令会访问 GitHub 远程仓库如果用户网络不稳定命令可能长时间不返回。BrewUI 一开始没有做超时控制有用户反馈“点击更新后界面一直转圈”。后来我在execa调用中加入了超时参数const { stdout } await execa(brew, args, { timeout: 120_000, });超过 120 秒直接抛错前端捕获后提示“命令执行超时可能是网络原因”。同时保留了“取消操作”的按钮点击后通过child.kill()终止当前进程。虽然这不一定能处理所有深度卡死的情况但绝大多数场景下用户能有一种手动干预的途径体验上比无限等待好很多。4.3 权限与 sudo 问题brew 的安装路径在不同 macOS 版本上不一样。Intel 芯片时代/usr/local需要管理员权限Apple Silicon 时代/opt/homebrew通常当前用户可以直接写入。但用户在安装某些包时仍可能遇到权限不足的错误。BrewUI 的应对策略是不在 GUI 里弹 sudo 密码框。为什么不弹因为sudo需要交互式终端Electron 处理起来麻烦而且让 GUI 应用直接持有 sudo 权限本身就是一种风险。我的做法是在日志里明确输出权限不足的提示并引导用户在终端里手动执行对应命令。这虽然不够“好看”但更安全也更实际。BrewUI 的本质是 Homebrew 的调起器而不是 Homebrew 的替代者遇到命令行都难解决的事强行在 GUI 里自动化反而容易出问题。4.4 UI 卡顿与内存占用安装了几百个包之后包列表的数据量会很大一次性渲染全部行会导致明显卡顿。我的优化方案是前端只渲染“可见区域”的数据也就是虚拟列表。Ant Design Table 本身支持虚拟滚动开启virtual属性即可。依赖树的渲染也是默认只展开前两层避免一次性创建几百个 DOM 节点。内存方面Electron 应用容易被吐槽吃内存。BrewUI 能做的主要是减少频繁的 JSON 大对象保存。每次刷新列表后前端只保留当前页面需要显示的字段而不是保存整个原始 JSON。这个习惯在数据量大时能明显低消内存峰值。一些个人体会BrewUI 这个项目做到后期我最大的感受是给一个成熟命令行工具做 GUI难点通常不在 GUI 本身而在于理解命令行工具自己的脾气。brew 的自动更新、锁机制、输出格式变化、网络不确定性每一个细节都会成为 GUI 需要应对的现实问题。好在 Homebrew 足够流行网上能搜到的坑也多我基本是“踩一个查一个查一个填一个”的状态。如果你正准备做一个类似的工具我的建议是先列一个“最小可用功能集合”比如“展示已安装列表 安装卸载 检查更新”这三点做出来已经能用了再逐步加上依赖图和批量操作。千万别一开始就想着把 brew 所有功能都搬到界面上那会把自己累死用户也不一定需要。工具类应用的灵魂是替用户省心而不是炫技。最后再分享一个小技巧BrewUI 里几乎每个长时间命令执行完成后我都会在状态栏显示一句“耗时 xx 秒”。这个数据看起来简单但用户能明确感知到操作是成功还是卡顿而不是对着转圈图标干猜。很多体验上的细节就是从这种一秒都不到的小反馈里建立起来的。
BrewUI：给Homebrew套上图形界面，让包管理不再依赖命令行
如果你和我一样平时主要靠终端管理 macOS 上的软件包每天在 Homebrew 里敲brew update、brew list、brew upgrade但又总觉得命令行不够直观——尤其是刚接触命令行不久的朋友看到一串brew leaves和依赖关系图就头大。这就是我最初想做 BrewUI 的原因给自己也给身边那些被 CLI 劝退的人做一个能看得见、点得动的 Homebrew 图形界面。BrewUI 本质上是一个围绕 Homebrew 的跨平台桌面工具核心能力包括展示已安装的 formula 和 cask、查看包依赖关系、执行安装/卸载/升级操作、清理旧版本和缓存。对于每天要与几十个包打交道的开发者和 macOS 重度用户来说它把那些需要死记的参数和不断翻文档的命令收拢成一个可视化的操作面板。这篇文章会从设计思路、核心模块、关键代码到实战踩坑完整复盘 BrewUI 的搭建过程如果你也想给自己的常用工具链做一个“看得见的外壳”可以直接拿这套思路往任何命令行工具上套。1. 为什么需要 BrewUI打包管理从“记参数”变成“看界面”1.1 命令行很好用但我承认它对新人不友好Homebrew 的能力确实强brew一条命令能解决依赖解析、下载、链接、版本切换一堆问题。但问题也在这里它把几乎所有能力都暴露给命令行而命令行对不常接触终端的人来说有天然的门槛。brew info的输出密密麻麻brew deps --tree的依赖树一长串更别提brew update和brew upgrade执行时那些白字蓝字的刷屏。我最初动手写 BrewUI就是发现团队里有同事用了几个月 Homebrew仍然只会install和uninstall想更新某个包前先 Google 半天。他们也试过商用工具和网上的管理面板但要么功能太少要么不贴合 Homebrew 的安装习惯要么需要额外起一个后台服务。我很确定在维护日常开发环境这件事上“可视化管理”比“记忆命令”更能减少心智负担。所以 BrewUI 的定位就很明确了它不是一个包管理器而是包管理器前面的一层可视化操作界面真正干活的还是 Homebrew 本身。这个定位决定了项目的核心思路BrewUI 要解决的问题不是“重新实现包管理”而是“让别人更容易使用包管理”。于是所有功能都围绕“展示状态”和“调起命令”两个方向展开前者负责把 Homebrew 的内部信息变成人能看懂的结构后者负责把人的点击翻译成 Homebrew 能执行的命令。这样一来无论 Homebrew 底层逻辑怎么变只要它的命令行接口还在BrewUI 的维护成本就相对可控。1.2 技术选型Electron 还是 Tauri我最后为什么选了 Electron桌面 GUI 有挺多方案我一开始列了三个纯 Electron、Tauri、以及一个偏轻量的方案——用 Python Qt。Python Qt 率先被排除因为要让用户看到漂亮的依赖图和流畅的列表滚动Web 技术栈的开发速度明显更快而且团队里 TypeScript 的经验更足。剩下就是 Electron 和 Tauri 的选择。Tauri 的优势是打包体积小、内存占用低用系统 WebView 渲染前端Rust 做后端。但有一个现实问题BrewUI 的主场景是频繁调用brew命令需要大量的子进程操作和流式输出解析。在 Tauri 里做这些也没问题不过当时 Tauri 的进程管理和 shell 插件还没有现在这么成熟我评估过之后觉得风险偏高。Electron 这边Node.js 的child_process生态非常完整execa、pidtree这些库可以直接用主进程和渲染进程之间的 IPC 也足够稳定。所以最后选择了 Electron Vite React。Electron 负责主进程、子进程调度和窗口管理React 负责界面Vite 负责开发热更新和构建打包。这套组合在今天看来依然很常规但对 BrewUI 这种工具型应用来说“常规”恰恰意味着少踩坑、好维护。提示如果你以后也想做类似工具选型时可以优先看“你熟悉的命令行语言的调用生态是否成熟”而不是单纯追求新技术。包管理类工具的核心是进程调用和输出解析这一层的稳定性比界面框架的噱头重要得多。2. 核心功能拆解BrewUI 做对了哪几件事2.1 包列表与状态同步区分 formula 和 caskHomebrew 里有两类安装对象formula 是命令行工具和库比如git、pythoncask 是图形化应用安装包比如google-chrome、visual-studio-code。这两种包的管理命令虽然都是brew install但展示方式、更新策略、卸载行为差异很大。BrewUI 的包列表不能把两者混在一起展示否则用户会看到一大串不认识的库名里混着几个 App寻找成本很高。我的做法是在列表页加一个 Tab 切换“命令行工具”和“图形应用”。切换时分别调用brew list --formula --json和brew list --cask --json拿到两个独立的数组。每个包卡片展示名称、当前版本、简介、安装路径和体积。状态方面brew 本身不提供“可更新列表”的常驻接口需要执行brew outdated --json才能拿到有新版可用的包所以 BrewUI 把“刷新状态”做成了一个统一的按钮点击后先跑brew outdated再刷新当前可见列表。这里有个细节值得说一下brew list默认返回很快但brew outdated因为要访问远程仓库通常要跑几秒到几十秒。如果每次启动都自动执行用户会明显感觉到卡顿。我在第一版里就栽过这个跟头后来改成“启动时只加载本地列表用户手动触发检查更新”或者提供一个可配置的自动刷新间隔默认 30 分钟。工具类应用最忌讳让用户等一个结果出来才能动能异步就异步能手动触发就不自动抢时间。2.2 安装、卸载与更新的命令封装把 brew 参数变成按钮BrewUI 的第二类核心功能是执行操作。安装、卸载、更新、清理这些操作本质上是给brew传递不同的子命令和参数。难的不是执行命令而是处理好“命令执行中”“执行成功”“执行失败”三种状态并且把输出变成用户可以理解的信息。以安装为例用户点击“安装”后前端调用主进程的runBrewCommand方法传入install、包名、--formula或--cask标记。主进程用execa执行并把 stdout 和 stderr 以流的方式实时回传到渲染进程。这样界面上可以显示一个滚动日志区域用户能看到下载进度和最终安装结果。安装结束后再触发一次“刷新状态”让列表里的新包出现。升级操作要稍微复杂一点因为brew upgrade后面可以接包名也可以不接。不接会升级所有可更新的包原则上很省事但实际使用中用户可能只希望升级某个包因为批量升级容易引入兼容性问题。所以 BrewUI 的默认设计是在“可更新”列表里每个包旁边放一个“升级”按钮同时在顶部保留一个“全部升级”的次要按钮以免用户误操作。这种细节看起来不起眼但决定了工具是“让人放心用”还是“让人担心点错”。2.3 依赖关系可视化把 brew deps 变成一棵看得懂的树依赖图是 BrewUI 最受好评的功能。brew deps --tree在终端里展示的是缩进文本包一多根本看不出来结构。BrewUI 把它变成了一棵可以展开和折叠的树形图。实现原理不复杂brew deps --json会输出一个包名到其直接依赖列表的映射关系。我拿到这个映射后从前台输入一个根包名比如ffmpeg递归查找它的依赖、依赖的依赖构建成一棵嵌套树。这里有个必须处理的坑依赖关系里可能存在循环引用比如 A 依赖 BB 又依赖 A如果不对节点做去重和访问标记递归会陷入死循环。我引入了一个visited集合每次遍历前先检查节点是否处理过处理过的直接返回一个引用占位符同时在 UI 上标注“已展示过”。最终渲染用的是 React 树组件可以按需展开和收起子树。考虑到有些包的依赖层级很深默认只展开两层更多层级延迟加载。真实使用下来这个功能比包列表更直观地回答了“这个包到底依赖了些什么”的问题也是 BrewUI 从“套壳列表”变成“真正有用工具”的关键点。3. 从零实现 BrewUI关键代码实录3.1 环境搭建与工程初始化BrewUI 基于 Electron Vite React项目结构分为主进程和渲染进程两部分。我使用electron-vite这个脚手架来统一管理它比手动配置 Webpack 或 Vite Electron 双进程省心很多。初始化命令npm create quick-start/electronlatest brewui -- --template react-ts cd brewui npm install装完依赖后的目录结构大概是这样的src/main主进程代码负责窗口创建、IPC 通信、子进程调用src/preload预加载脚本用contextBridge暴露安全接口给渲染进程src/rendererReact 界面代码electron-builder.yml打包配置开发阶段运行npm run devVite 会启动渲染进程的本地服务Electron 再加载这个地址。生产构建时npm run build会把渲染进程打包成静态文件由 Electron 直接加载。这个流程如今已经很成熟我建议你第一次做的时候直接沿用这套模板别从零搭配置。3.2 数据访问层用 JSON 和 brew 对话BrewUI 的所有数据都来自 Homebrew 的命令行输出。为了保证解析稳定我尽量让 brew 输出 JSON 格式而不是解析文本。Homebrew 对大部分常用命令都内置了--json参数brew info --jsonv2 --formula git brew list --formula --jsonv2 brew outdated --jsonv2 brew deps --json --formula ffmpeg这样拿到的就是结构化数据解析起来远比文本可靠。我在主进程里写了一个统一的命令执行模块用execa执行命令并返回解析后的 JSON// src/main/brew.ts import { execa } from execa; export async function runBrewJson(args: string[]) { const { stdout } await execa(brew, args, { env: { ...process.env, HOMEBREW_NO_AUTO_UPDATE: 1 }, }); return JSON.parse(stdout); } export async function getInstalledFormula() { return runBrewJson([list, --formula, --jsonv2]); } export async function getOutdated() { return runBrewJson([outdated, --jsonv2]); } export async function getDeps(fullName: string) { return runBrewJson([deps, --json, --formula, fullName]); }这里有一个关键环境变量HOMEBREW_NO_AUTO_UPDATE1。Homebrew 在跑很多命令之前可能会自动git pull更新自身这在交互式终端里问题不大但在 GUI 工具里会拖慢命令响应事件甚至因为网络问题卡很久。设置这个环境变量之后brew 会跳过自动更新让命令执行速度明显提升。代价是它会输出一条提示信息但--json模式下的正式输出并不受影响。再说execa这个库。Node.js 原生也有child_process.exec和spawn但execa的 API 更友好支持 promise 封装、流式输出、超时控制。它内部已经把 stdout 和 stderr 做了收流对常见情况处理得非常好。在只拿 JSON 的场景直接await即可。3.3 前端界面与交互设计别让用户等白屏前端部分我用了 React 和 Ant Design 的组件库因为表格、按钮、消息提示这些基础组件可以省很多事。包列表直接用 Table依赖树用 Tree操作反馈用 message。状态管理没有引入 Redux 这类重库只在 React 组件内部用useReducer管理“加载中”“成功”“失败”三种状态栈因为 BrewUI 的状态其实不复杂一个包列表、一个更新列表、一个正在执行命令的队列。执行命令时的防重复操作非常关键。比如用户连续点击两次“安装”可能会拉起两个 brew 进程互相抢锁。这个问题一度让我很头疼。brew 自己有一个锁机制在同一时刻只能有一个写操作执行第二个命令会等很久甚至直接失败。所以 BrewUI 在前端做了“按钮级 loading”点击后按钮变为 loading 状态禁用所有影响同一包的操作等命令执行完再恢复。更进一步我在主进程里维护了一个全局任务队列同一个时间只允许一个 brew 写操作执行其余进入等待队列// src/main/queue.ts let running false; const queue: Array() void []; export async function enqueueBrewTaskT(task: () PromiseT): PromiseT { return new Promise((resolve, reject) { queue.push(async () { try { const result await task(); resolve(result); } catch (error) { reject(error); } }); processQueue(); }); } async function processQueue() { if (running) return; running true; while (queue.length 0) { const task queue.shift(); if (task) await task(); } running false; }这个队列避免了多个写操作同时执行导致的锁等待问题也让界面上“当前有几个操作排队中”的提示变得很简单queue.length 就是排队数量。命令执行的日志展示我采用的是“实时回传 滚动到底部”的方式。主进程用execa的stdio: [inherit, pipe, pipe]拿到流再通过webContents.send(command-log, chunk)把每一段输出推给渲染进程。渲染进程收集到日志数组后用ref控制容器在每次内容更新后滚动到底部。这里注意不要用innerHTML直接插入日志文本因为命令输出可能包含特殊字符直接用文本节点设置更安全。3.4 打包与分发从开发到可安装开发完成后接入打包流程。Electron 应用打包用electron-builderBrewUI 的打包目标是 macOS 上的 dmg 和 zip。配置里有几个关键点files字段要包含dist目录和主进程代码不要把所有源码都打进去。macOS 签名和公证需要开发者证书我没有单独买开发者账号所以本地测试时用的是跳过签名的配置真机验证通过后再走签名流程。这个过程有点麻烦但 App Store 外的 macOS 应用不签名很难运行在配置里加MACOS_SKIP_SIGNING环境变量可以暂时跳过。因为 brew 命令在打包后的应用里依然可用所以运行时依赖的就是系统里真实的 Homebrew不需要把 brew 一起打包。# electron-builder.yml appId: com.example.brewui productName: BrewUI directories: output: release files: - out/** - package.json mac: target: - dmg - zip category: public.app-category.developer-tools打包完成后 dmg 大概几十 MB对 Electron 应用来说已经算小了。安装后第一次启动BrewUI 会自动检测系统是否安装了 Homebrew如果没有安装会引导用户去官网执行安装命令而不是在 GUI 内部尝试安装。这个设计很保守但避免了权限和环境变量一堆问题。4. 常见问题与排查技巧实录4.1 brew 输出格式变化导致解析失败Homebrew 的更新频率很高命令行输出的格式偶尔会变。BrewUI 最严重的一次事故是brew list --jsonv2输出的字段名从versions变成了installed_versions之类的调整导致前端拿不到版本号。排查这个问题的方式是在主进程里加一个“原始输出查看”功能界面上可以一键复制最后一次命令的原始 stdout。这样当用户反馈“版本没显示”时我可以先看原始 JSON判断是 brew 改了格式还是代码解析问题。后续为了降低这类问题的发生率我在解析 JSON 时用了解构赋值加默认值const version item.versions?.stable ?? unknown;这样即使字段缺失界面也不会直接崩溃。4.2 子进程卡死与超时brew 某些命令会访问 GitHub 远程仓库如果用户网络不稳定命令可能长时间不返回。BrewUI 一开始没有做超时控制有用户反馈“点击更新后界面一直转圈”。后来我在execa调用中加入了超时参数const { stdout } await execa(brew, args, { timeout: 120_000, });超过 120 秒直接抛错前端捕获后提示“命令执行超时可能是网络原因”。同时保留了“取消操作”的按钮点击后通过child.kill()终止当前进程。虽然这不一定能处理所有深度卡死的情况但绝大多数场景下用户能有一种手动干预的途径体验上比无限等待好很多。4.3 权限与 sudo 问题brew 的安装路径在不同 macOS 版本上不一样。Intel 芯片时代/usr/local需要管理员权限Apple Silicon 时代/opt/homebrew通常当前用户可以直接写入。但用户在安装某些包时仍可能遇到权限不足的错误。BrewUI 的应对策略是不在 GUI 里弹 sudo 密码框。为什么不弹因为sudo需要交互式终端Electron 处理起来麻烦而且让 GUI 应用直接持有 sudo 权限本身就是一种风险。我的做法是在日志里明确输出权限不足的提示并引导用户在终端里手动执行对应命令。这虽然不够“好看”但更安全也更实际。BrewUI 的本质是 Homebrew 的调起器而不是 Homebrew 的替代者遇到命令行都难解决的事强行在 GUI 里自动化反而容易出问题。4.4 UI 卡顿与内存占用安装了几百个包之后包列表的数据量会很大一次性渲染全部行会导致明显卡顿。我的优化方案是前端只渲染“可见区域”的数据也就是虚拟列表。Ant Design Table 本身支持虚拟滚动开启virtual属性即可。依赖树的渲染也是默认只展开前两层避免一次性创建几百个 DOM 节点。内存方面Electron 应用容易被吐槽吃内存。BrewUI 能做的主要是减少频繁的 JSON 大对象保存。每次刷新列表后前端只保留当前页面需要显示的字段而不是保存整个原始 JSON。这个习惯在数据量大时能明显低消内存峰值。一些个人体会BrewUI 这个项目做到后期我最大的感受是给一个成熟命令行工具做 GUI难点通常不在 GUI 本身而在于理解命令行工具自己的脾气。brew 的自动更新、锁机制、输出格式变化、网络不确定性每一个细节都会成为 GUI 需要应对的现实问题。好在 Homebrew 足够流行网上能搜到的坑也多我基本是“踩一个查一个查一个填一个”的状态。如果你正准备做一个类似的工具我的建议是先列一个“最小可用功能集合”比如“展示已安装列表 安装卸载 检查更新”这三点做出来已经能用了再逐步加上依赖图和批量操作。千万别一开始就想着把 brew 所有功能都搬到界面上那会把自己累死用户也不一定需要。工具类应用的灵魂是替用户省心而不是炫技。最后再分享一个小技巧BrewUI 里几乎每个长时间命令执行完成后我都会在状态栏显示一句“耗时 xx 秒”。这个数据看起来简单但用户能明确感知到操作是成功还是卡顿而不是对着转圈图标干猜。很多体验上的细节就是从这种一秒都不到的小反馈里建立起来的。
