BrewUI这个名字来源于我一次不经意的抱怨。那时候我刚给一台新Mac配完开发环境照例用Homebrew装了七八十个包一切正常。但当我试图回答一个很基础的问题——这台机器现在到底装了些什么有没有哪些包已经没人依赖、可以安全清掉——我连续敲了brew list、brew leaves、brew outdated三个命令输出叠在一起接近三百行来回切换终端窗口才勉强拼出全貌。那一刻我的感受很明确brew是个好工具但它缺一层视图层。BrewUI不是一个替代终端的产品正相反它把brew原有的命令执行体系原封不动保留下来只是在上面加了一层图形化的决策支持层。它用Electron React构建底层通过解析brew info --jsonv2这类原生JSON输出提供包浏览、依赖关系图谱、升级选择、清理建议这几块能力。如果你平时靠brew管理一堆开发依赖又受不了在满屏文本里找版本号和依赖关系这篇文章里的选型思路和踩坑记录应该对你有用。1. 为什么我给brew套了一层UI而不是换掉终端1.1 一个常年用终端的人为什么开始嫌弃brew的浏览层前面提到的那次经历其实只是压垮我的最后一根稻草。真正让我意识到问题的是一次更复杂的升级操作我想升级某个包但不确定它会不会影响到其他正在用的工具。那天的操作路径是先brew deps --tree看依赖再brew uses --installed看反向引用再打开几个issue页面人工确认版本兼容性。整个过程花了差不多二十分钟。依赖这种东西在终端里能查但查出来的是一条条扁平的文本层级关系要靠眼睛在括号和箭头之间去找。这不是brew的缺陷而是终端交互范式的天然局限。终端擅长精确检索和批量执行它不擅长的是空间布局、关系可视化、状态概览。打个比方命令行像挨个翻快递单号一个单号一个结果GUI像看一张仓库货架分布图一眼就知道哪些区域堆得多、哪些标签过期了。在精确知道要做什么的场景里命令行永远更快但在先搞清楚有什么、状态怎么样、合不合理的场景里一张图确实胜过三百行字。1.2 BrewUI要解决的其实是三个决策问题做BrewUI之前我先把日常对brew的操作拆了一遍发现大部分时间卡在三个问题上而不是卡在命令本身依赖判断包A升级之后会不会牵连包B哪些包还是孤儿时机判断这么多可升级的包哪些值得现在升、哪些应该再等等清理判断哪些依赖删了不会影响现有环境这三个问题在终端里都能答但答得慢而且没有一个统一的上下文可以把它们放在一起看。BrewUI的核心价值就是把这三种决策工作流图形化包列表用来做概览和浏览定位依赖图谱用来回答改一个会影响谁升级暂存区用来把升级从一个简单动作变成一个连续思考的过程。我在定技术方案之前先把到底要解决什么问题写在了项目README第一行BrewUI是Homebrew的可视化决策支持层而不是又一个终端模拟器。这句话后来帮了很大的忙——每当我想加一个华而不实的功能时就回头看这行字放弃了很多没有必要的复杂度。2. 技术选型与数据通路GUI和brew是怎么对话的2.1 从Swift到Tauri再到Electron我最终选了谁一开始我考虑的是原生Swift AppKit。brew本身就绑定macOS原生方案做出来的应用体积小、启动快、和系统集成也好。但很快我意识到两个问题第一依赖图谱需要大量迭代SwiftUI里没有足够成熟的图编辑库很多绘制逻辑得自己从底层写第二我很清楚这个项目日后大概率要支持Linuxbrew环境纯原生路线等于把自己锁死在Apple生态里。后来我看了Tauri。Tauri的体积控制和前端生态确实诱人但当时身边没有人为它维护一条Rust的构建链。对BrewUI这个场景来说最终决定性的因素不是安装包大小而是我能把精力放在数据逻辑和交互上。Electron的生态成熟度在这里占了绝对优势React、Ant Design、xyflow/react这一套下来开发效率是原生方案的好几倍遇到问题也更容易找到现成答案。方案优点缺点我的结论Swift/AppKit原生、体积小、系统集成好跨平台难、图谱类组件稀缺放弃Tauri体积小、内存可控Rust构建链维护成本高暂缓Electron生态强、迭代快、跨平台包体积大、内存占用高选用体积和内存的缺点在BrewUI这个项目里其实可以接受——它是辅助工具不是常驻后台应用。而且Electron的进程模型反而帮了我一把后面讲PATH坑的时候你会发现它逼着我用更工程化的方式去处理外部命令调用。2.2 数据源把brew自己的输出变成可读的数据模型BrewUI最关键的架构决定是数据来源只用brew自己不自己发明数据格式也不替代brew去操作任何数据库。这样做的好处是brew升级、Homebrew内部数据结构变化都不需要我同步维护一套并行的实现。核心数据源是这条命令的输出brew info --jsonv2它返回的是一整份JSON包含formulae和casks两个数组。每个formula对象里又有name、versions、dependencies、dependents、installed等字段。一次调用就能拿到整个包管理器视图的大部分数据完全不需要为了列一个包表就spawn几十次命令。我把这份输出称为BrewUI的数据库快照所有页面初始化时都从这份快照出发。我针对这份JSON写了一个adapter层目的不是美化数据而是做两件事第一把不同brew小版本之间的字段差异抹平后面会讲为什么必须做第二把是否需要额外扫描的决策集中在这一层。比如brew的输出里其实没有已安装包占用磁盘大小这个字段需要在adapter里去扫描前缀目录下的Cellar目录才能补全。扫描时用文件系统的stat统计真实磁盘占用而不是简单累加文件大小否则页面里显示的数字会和系统报告对不上用户一眼就能看出数据不靠谱。2.3 主进程、渲染进程和worker的职责划分Electron有三层进程模型主进程、渲染进程、以及我额外引入的worker子进程。这里有几个原则务必守住渲染进程不能直接执行child_process。要做Node相关的事情一律通过preload暴露的IPC接口转发到主进程否则一旦开启contextIsolation渲染进程就是个纯浏览器环境。主进程只是搬运工不应该执行耗时命令本身。主进程负责接收参数、转发给worker、再把worker的进度事件推送回渲染进程。长任务brew update、brew upgrade、brew install必须放到独立worker进程里因为Electron主进程一旦阻塞整个应用包括窗口事件、快捷键、最小化动画全部会跟着卡。我用的是child_process.fork来做worker。fork的好处是天然有message通道不需要自己处理stdout解析和序列化而且子进程崩溃不影响主进程。每个任务一个worker跑完即销毁任务状态机只有running、success、failed三种。这套结构定下来之后后面遇到的PATH问题、锁冲突问题、长任务卡死问题都因为结构比较清晰而容易定位。3. 核心模块拆解包列表、依赖图谱、升级与清理四个界面3.1 包列表把三百行终端输出变成一张可扫读的表格BrewUI的主界面不是一行命令而是一张表格。列设计是包名、类型formula还是cask、已装版本、最新版本、安装大小、被依赖数、状态标记。这里最容易被忽略的细节是被依赖数这一列。它不是额外调用brew uses得到的而是从brew info --jsonv2返回的全局数据里对每个包做一次反向依赖汇总。由于所有数据都在同一份JSON里这一步用纯JavaScript的Map就能完成毫秒级出结果。这一列看似简单实际价值非常大——它能在半秒内告诉我某个包一旦卸载会有多少个包失去依赖。实现这张表时排序和筛选我放在前端做。列表最多也就几百个项目前端过滤完全没有压力没必要引入服务端分页的复杂度。但有一个细节容易踩坑版本号排序不能按字符串排否则10.0会排在9.0前面。我给表格的排序器写了一个简单的semver比较函数不依赖额外库split(.)后再逐位转Number比较就够了。3.2 依赖图谱为什么我放弃了力导向图改用dagre分层布局依赖图谱是第一版最让我兴奋的模块。一开始我毫不犹豫选力导向图因为看起来酷节点和连线会自动弹开。但在装了几百个包的机器上物理模拟直接把界面卡成幻灯片节点互相堆叠根本没法解读。后来我把方案换成了dagre的分层布局。dagre是一个有向分层布局库它会把所有节点按照依赖层级排成行列看起来像组织结构图也像管网图。配合xyflow/react做渲染同样几百个节点帧率稳定很多。关于依赖方向我在界面上默认画的是A依赖B则A连向B从任意包出发顺着连线往下走能看到完整依赖链反过来点击节点时高亮所有连向它的边一眼看出谁在依赖这个包。这个交互细节非常关键高亮反向依赖做出来之后误删包的风险大大降低。代码如下核心就是把图数据灌给dagre让它算出坐标import dagre from dagrejs/dagre; import { ReactFlow, Background } from xyflow/react; const g new dagre.graphlib.Graph(); g.setGraph({ rankdir: LR }); g.setDefaultEdgeLabel(() ({})); nodes.forEach((n) g.setNode(n.id, { width: 160, height: 40 })); edges.forEach((e) g.setEdge(e.source, e.target)); dagre.layout(g); const laidOutNodes nodes.map((n) { const pos g.node(n.id); return { ...n, position: { x: pos.x, y: pos.y } }; });画图只是第一步真正有价值的是剪枝。我默认只显示已安装节点未安装的深层依赖不画出来否则图谱上会出现一大片灰色点既没有操作入口也没有决策意义。页面上也放了一句直白的说明这里的图是本机已装视角不是上游的全量依赖网。3.3 升级暂存区把要不要升级变成一次有意识的决策brew upgrade --all这个命令本身没有错但直接全量升级很容易陷入升级没看坑、回头一坨问题的状况。BrewUI里我把升级做成了一种暂存区交互界面上有一个面板专门列brew outdated的结果每个包旁边有四个信息——当前版本、新版本、被依赖数、版本发布说明摘录。你可以把想升级的包逐个点击加入暂存区再统一点击执行升级。执行时传入的命令是brew upgrade pkg1 pkg2而不是全量升级。这样做的意图很明确让每一条升级都经过一次有意识的决策而不是闭眼一把梭。执行面板里有一个选项我也花了些心思——升级前是否执行brew update。第一版我漏掉了这个选项结果每次点升级都要先等上几十秒的brew update有些用户包括我自己真的很烦。加回来之后这条决策链才算真正完整。3.4 清理体检识别那些可以安全删除的孤儿依赖brew autoremove能清理不再被任何已安装包依赖的孤儿依赖但很多人不敢跑因为终端不会告诉你删了这些之后什么会受影响。BrewUI里把这块做成了清理体检面板面板列出brew autoremove将要删除的包同时为每个包标注被依赖数。按照Homebrew的设计能被autoremove的包被依赖数本来就是0但面板里我还是显示了这条信息——不是因为它有信息量而是因为能让用户看到确实安全。执行前应用会要求用户输入当前用户名单词相当于第二道确认。这里有一个我个人的设计习惯凡是删除类按钮都要比安装/升级按钮多一道确认动作。因为删除的代价是隐性的一旦删错恢复成本往往比安装时高得多。4. 开发过程中我踩到的四个坑以及绕过方式4.1 brew的JSON输出并不是稳定API第一条经验是brew info --jsonv2的输出在brew的版本演进中并不稳定。不是字段命名整天变而是某些字段在部分版本里不会返回或者缺省值的类型不同。比如dependents这个字段我遇到过缺失的情况也遇到过返回空数组的情况如果不做防御性处理render的时候一个undefined就能让整个表格崩掉。解决办法是在adapter层里对所有字段做兜底解析时统一用可选链和默认值把字段缺失和空数组规范成同一形态。更关键的是我在CI里加了一组brew版本兼容性自测每次brew升级后跑一遍确保解析逻辑没有假阴性。这套自测代码量不大但价值极大——它防止了用户一升级HomebrewBrewUI就抛异常这类最糟糕的体验。4.2 GUI应用的PATH里没有/opt/homebrew/bin这个坑可能让所有写过Electron GUI的人都心领神会。在macOS上通过访达或Spotlight启动的GUI应用继承的不是你终端里的shell环境而是一个最小化的环境变量集合。换句话说代码里直接写spawn(brew)根本找不到brew可执行文件跟你直接在终端里敲brew完全是两个世界。解决方式不复杂但必须前置在应用启动时先通过/bin/zsh -lc command -v brew拿到brew的绝对路径再通过brew --prefix拿到前缀目录之后所有调用都用绝对路径一步到位不再依赖PATH。这段探测逻辑还要处理brew不存在的场景给用户弹出清晰的引导提示而不是一句让人摸不着头脑的ENOENT。这个坑之所以值得单独拿出来讲是因为它几乎不会在开发阶段暴露——开发时你通常从终端启动Electron终端已经load了完整PATH只有打包成.app之后从访达启动问题才出现。4.3 并发执行brew命令时的进程互斥Homebrew自身有文件锁机制防止两个brew进程同时改数据库。但BrewUI作为GUI用户很可能一边在应用里点升级一边又去终端敲brew install两个进程一撞brew就报出Another active Homebrew process is already in progress。这个问题的处理分两层。第一层执行任何写操作前先检测锁检测到就给出友好提示并自动等待而不是直接弹一个失败的对话框。第二层如果等待时间过长我设定了五分钟上限超时就冻结UI的写操作入口只保留只读能力等锁释放再解除冻结。从产品角度说两个写操作撞车在GUI里尤其常见因为用户看不到另一个进程在忙所以一定要做好排队提示不能假装这事不会发生。4.4 长任务在IPC回调里把UI拖垮初期版本我犯过一个低级但典型的错误在ipcMain.handle里面直接await一个spawn出来的brew upgrade进程。结果就是整个窗口在升级期间处于假死状态日志也收不全因为stdout缓冲区没有被及时消费。后来我彻底改成了fork worker 流式推送的架构渲染进程通过IPC发起任务拿到一个taskId主进程fork一个worker去执行brew命令worker把stdout/stderr按行通过message推送回主进程主进程用webContents.send把同样的消息广播给渲染进程UI上做一个可折叠的日志抽屉实时显示brew的输出底部显示当前状态。这样做的附带收益是用户终于能在UI里看到brew update到底卡在哪一步了。很多应用无响应的问题根源其实是没有反馈而不是没有进展。5. 从零跑通一个最小可用版BrewUI5.1 初始化工程下面这套步骤是我建议后来者的最小复现路径。不用一上来就复刻全部面板先把点一个按钮 - 跑一条brew命令 - 把JSON显示成表格这条链路跑通后面加功能都是水到渠成的事。npm create vitelatest brewui -- --template react-ts cd brewui npm install electron electron-builder xyflow/react dagrejs/dagre antd前端框架方面我选了React TypeScriptVite做构建。TypeScript在这个项目里不是可选项因为brew的JSON结构非常复杂没有类型定义的话adapter层很快就得靠猜字段名过日子。我手写了几个核心接口类型比如FormulaInfo、CaskInfo虽然花了一些时间但后面所有页面都受益于这份类型约束。5.2 主进程执行brew命令的核心代码主进程放一个创建worker的辅助函数// electron/main/brew.js const { fork } require(child_process); function runBrewTask(args, handlers) { const worker fork(__dirname /brewWorker.js); worker.on(message, (msg) { if (msg.type stdout || msg.type stderr) { handlers.onLog?.(msg.data); } else if (msg.type done) { handlers.onDone?.(msg); } }); worker.send({ args }); }worker的实现就是上一章提到的spawn逻辑// electron/main/brewWorker.js const { spawn } require(child_process); process.on(message, (msg) { const [brewPath, ...args] msg.args; const child spawn(brewPath, args, { stdio: [ignore, pipe, pipe] }); child.stdout.on(data, (chunk) { process.send({ type: stdout, data: chunk.toString() }); }); child.stderr.on(data, (chunk) { process.send({ type: stderr, data: chunk.toString() }); }); child.on(close, (code) { process.send({ type: done, code }); }); });注意worker里第一行就把args拆成了brewPath和剩余参数这正是4.2节里用绝对路径执行brew的落地写法。5.3 渲染进程里最简单的一张包列表在preload里暴露接口// electron/preload.js const { contextBridge, ipcRenderer } require(electron); contextBridge.exposeInMainWorld(brewUI, { runBrew: (args) ipcRenderer.invoke(brew:run, args), onLog: (cb) ipcRenderer.on(brew:log, (_e, msg) cb(msg)), });React组件里直接调用function App() { const [rows, setRows] useState([]); useEffect(() { window.brewUI.runBrew([info, --jsonv2]).then((res) { const data JSON.parse(res.stdout); setRows(data.formulae); }); }, []); return ( table thead trth名称/thth当前版本/thth最新版本/thth被依赖数/th/tr /thead tbody {rows.map((f) ( tr key{f.name} td{f.name}/td td{f.installed?.[0]?.version ?? -}/td td{f.versions?.stable ?? -}/td td{f.dependents?.length ?? 0}/td /tr ))} /tbody /table ); }这段代码处理了前面提到的大部分边界情况installed可能是空数组dependents可能是undefined全部用默认值兜住。第一次跑通的时候看到表格上铺满真实机器上的包那种数据流动起来了的感觉是写这个项目最爽的一刻。5.4 跑起来之后的调试建议开发模式下的一个小技巧在Electron里开两个输出设备一个是主进程的console一个是渲染进程的DevTools console。brew命令的调试信息统一打到主进程渲染进程只接收已经清洗过的数据。这样定位问题的时候一眼就能看出是命令没跑成还是数据展示错了。另外我在开发环境的启动参数里加了--unhandled-rejectionsstrict让任何未处理的Promise错误直接崩溃而不是静默吞掉。GUI应用最怕无声失败错误越早在开发阶段暴露越好拖到用户手里才出问题排查成本就高多了。6. 边界感与下一步规划6.1 什么时候应该回到终端BrewUI能覆盖我大概80%的日常检查场景但我从没打算用它替代所有brew操作。有几种情况我会毫不犹豫地切回终端脚本化和CI场景brew upgrade --all一条命令干净利落应急修复场景包损坏导致应用起不来终端里重装通常比GUI里层层点击快单条包信息查询brew info package几个字就能搞定开GUI反而显得重。做工具一定要有边界感。一个GUI如果什么功能都往里塞最后往往哪个都不好用。BrewUI的定位始终是决策支持层不是brew的全部。这个边界写进README之后用户在提需求时也更清楚这个工具擅长什么、不擅长什么反而减少了无效沟通。6.2 我接下来打算给BrewUI加的东西目前已经在推进的功能有三个。第一个是Brewfile可视化编辑器把Brewfile从一行行文本变成可勾选的清单还能对比不同机器之间的差异。第二个是多机对比导入两台机器的brew list逐个比较版本差异方便团队统一开发环境。第三个是更新审计报告升级操作后生成一份Markdown报告记录升级前后版本、耗时、失败项方便事后追溯。报告导出这块我已经写了一半等稳定后会单独分享。6.3 写完之后我对brew的理解变化最后说点感性的。很多人以为做可视化工具就是把数据画成图表但真正做完BrewUI之后我更强烈的感受是可视化逼着我把brew的数据流彻底搞懂了。以前我只知道brew install能装包现在我对它输出里的每个字段、每条命令之间的依赖关系都有了具体的把握。这个过程反过来让我用命令行的水平也上了一个台阶——现在我在终端里更清楚该查什么、怎么查。如果你也想做类似的项目我最想给的建议是先别急着写UI先花一个下午把brew info --jsonv2的完整输出扒一遍认真看每个字段的含义再决定要做哪一块。你会发现最花时间的不在画图而在理解数据、清洗数据、建模数据。这才是这类工具真正的难点也是它真正值钱的地方。