1. 从 t3code 这个标题说起一个跨平台 CLI 工具链的完整落地思路第一次看到 t3code 这个标题的时候我脑子里蹦出来的第一个念头是这大概率又是一个把命令行工具打包成桌面应用的项目。为什么这么判断因为热搜词里同时出现了 Electron、CLI、Homebrew、winget 这几个关键词这个组合太典型了——它几乎就是用 Electron 做壳把一套 CLI 工具链分发给 Mac 和 Windows 用户的标准配方。我这些年折腾过不少类似的工具从早期的纯脚本分发到后来用 Homebrew Tap 做 Mac 端安装再到用 winget 做 Windows 端分发中间踩的坑能写一本书。t3code 这个项目本质上要解决的问题是如何让一个以命令行交互为核心的工具既能保留 CLI 的高效又能让不熟悉终端的用户通过图形界面用起来同时还要解决跨平台安装和更新的问题。这篇文章我会把 t3code 这类项目的完整实现路径拆开讲。从整体架构怎么设计、Electron 壳和 CLI 内核怎么通信、Homebrew 和 winget 的打包分发怎么做、到实际开发中会遇到哪些坑我都会结合自己的实操经验说清楚。不管你是想自己做一个类似的工具还是想理解这类项目的运作原理或者只是好奇为什么现在这么多 CLI 工具都开始套 Electron 壳这篇内容应该都能给你一些能直接抄作业的东西。适合的读者范围我划一下有基本 Node.js 和命令行使用经验的同学看起来会最顺但如果你是完全的新手我也会把关键概念用生活化的方式解释清楚保证你能跟上。整篇内容会围绕 t3code 这个核心场景展开不会跑偏到无关的技术话题上。2. 整体架构设计为什么是 Electron 加 CLI 的组合2.1 核心需求拆解与方案选型逻辑要理解 t3code 为什么选择 Electron CLI 这个架构得先想清楚它要服务的两类用户。一类是重度终端用户他们希望直接在命令行里敲t3code就能干活追求的是速度和可脚本化另一类是普通用户他们不熟悉终端需要一个能点按钮、看界面的应用。这两类用户的需求看起来是矛盾的但 Electron CLI 的组合恰好能同时满足。具体来说CLI 内核负责所有实际的功能逻辑——文件处理、代码转换、网络请求等等它是纯 Node.js 写的可以独立运行。Electron 壳则是一个图形界面它通过子进程调用 CLI 内核把结果展示在界面上。这样做的好处是核心逻辑只写一遍CLI 用户和 GUI 用户用的是同一套东西不会出现命令行能用但界面报错这种分裂情况。我试过另一种方案就是把逻辑直接写在 Electron 的主进程里然后单独再写一套 CLI。实测下来维护成本翻倍因为任何功能改动都要改两个地方时间一长必然不同步。所以 t3code 选择 CLI 优先、Electron 包装的思路从工程角度看是更稳的。提示CLI 内核和 Electron 壳之间一定要有清晰的边界。我的做法是把 CLI 做成一个独立的 npm 包Electron 只是它的一个消费者。这样即使以后想换掉 Electron 换成 Tauri 或者别的方案CLI 部分完全不用动。2.2 Electron 壳与 CLI 内核的通信机制通信这块是很多人容易搞混的地方。Electron 有主进程main process和渲染进程renderer processCLI 内核跑在哪个进程里直接决定了通信方式。我的建议是CLI 内核作为独立子进程运行通过标准输入输出stdio和主进程通信。为什么不用 Electron 的 IPC 直接调因为 CLI 内核需要能独立运行如果它依赖 Electron 的 IPC 机制那就没法单独当命令行工具用了。用子进程 stdio 的方式CLI 内核完全不知道 Electron 的存在它只是正常地读参数、输出结果。具体实现上主进程用 Node.js 的child_process.spawn启动 CLI然后监听 stdout 和 stderr。渲染进程通过 IPC 把用户操作发给主进程主进程再转发给 CLI 子进程。返回的数据沿着反方向传回去。这套链路听起来绕但每一层职责都很清晰调试的时候也容易定位问题出在哪一环。// 主进程中启动 CLI 子进程的简化示例 const { spawn } require(child_process); const path require(path); function runCli(args, onData, onError) { const cliPath path.join(__dirname, .., cli, bin, t3code.js); const child spawn(node, [cliPath, ...args]); child.stdout.on(data, (data) { onData(data.toString()); }); child.stderr.on(data, (data) { onError(data.toString()); }); child.on(close, (code) { console.log(CLI 进程退出退出码: ${code}); }); return child; }这段代码的关键点在于spawn而不是exec。exec会把所有输出缓冲到内存里输出量大时会出问题spawn是流式的适合处理持续输出的场景。另外注意路径处理打包后 CLI 文件的路径会变用path.join配合__dirname比硬编码路径靠谱得多。2.3 跨平台分发的整体策略分发是 t3code 这类项目最容易被低估的环节。Mac 用户习惯用 HomebrewWindows 用户习惯用 winget如果你只提供一个下载链接让他们手动装转化率会低得可怜。所以 t3code 需要同时维护 Homebrew 的 formula 和 winget 的 manifest。这里有个决策点Electron 应用本身和 CLI 工具是分开分发的还是打包在一起我的做法是分开。CLI 通过 npm 和 Homebrew/winget 分发Electron 应用通过各自的安装包分发。这样 CLI 用户可以只装 CLI不需要下载几百兆的 Electron 运行时。对于只需要命令行功能的用户来说这个体验差别很大。3. 核心细节解析Electron 壳的关键实现要点3.1 主进程与渲染进程的职责划分Electron 的主进程负责窗口管理、菜单、系统集成这些事渲染进程负责界面展示。t3code 这类工具的主进程还需要额外承担一个职责管理 CLI 子进程的生命周期。比如用户关闭窗口时要确保 CLI 子进程也被正确终止否则会留下僵尸进程。我踩过的一个坑是在开发环境下热重载会导致主进程重启但之前启动的 CLI 子进程不会被自动清理。时间一长后台堆了一堆进程把内存吃满了。解决办法是在主进程的before-quit事件里显式杀掉所有子进程。const children new Set(); app.on(before-quit, () { for (const child of children) { if (!child.killed) { child.kill(SIGTERM); } } });渲染进程这边我建议用 preload 脚本做一层安全隔离不要直接开nodeIntegration。虽然 t3code 是本地工具风险相对低但养成好习惯总没错。preload 里通过contextBridge暴露有限的 API 给渲染进程这样即使界面代码有漏洞也不会直接拿到 Node.js 的全部能力。3.2 Electron 菜单与快捷键的设计Electron 的菜单系统在 Mac 和 Windows 上行为差异很大。Mac 有全局菜单栏Windows 是每个窗口一个菜单。t3code 如果要提供新建任务打开配置查看日志这些操作菜单设计得考虑两套逻辑。我的经验是核心操作一定要有快捷键菜单只是辅助。因为 CLI 用户本来就习惯键盘操作给他们一个CmdOrCtrlN新建任务比让他们去菜单里找快得多。Electron 的accelerator字段支持CmdOrCtrl这种跨平台写法Mac 上自动映射成 CmdWindows 上映射成 Ctrl。const template [ { label: 文件, submenu: [ { label: 新建任务, accelerator: CmdOrCtrlN, click: () { mainWindow.webContents.send(menu:new-task); } }, { type: separator }, { label: 退出, accelerator: CmdOrCtrlQ, role: quit } ] } ];注意role: quit这种用法Electron 内置了一批标准角色用 role 比自己写 click 处理更可靠因为它会自动适配平台行为。比如 Mac 上退出是 CmdQWindows 上是 AltF4用 role 就不用自己判断平台了。3.3 本地服务与 localhost 通信的取舍热搜词里出现了 electron localhost这通常是指 Electron 应用在本地起一个 HTTP 服务然后界面通过 localhost 访问。这种模式在某些场景下有用比如需要和浏览器扩展通信或者需要让外部工具调用应用的功能。但对于 t3code 这类工具我的建议是能不用 localhost 就不用。原因有三一是端口冲突问题用户机器上可能已经有别的服务占了那个端口二是安全问题本地服务如果没做好鉴权同机器上的其他程序可以随意调用三是增加了复杂度本来 IPC 能解决的事绕一圈走 HTTP 没必要。如果确实需要本地服务一定要做两件事端口用 0 让系统自动分配然后把实际端口通过 IPC 告诉渲染进程服务只监听 127.0.0.1绝对不要监听 0.0.0.0。4. 实操过程从零搭建 t3code 的完整流程4.1 项目初始化与目录结构设计我一般会用一个 monorepo 的结构来组织 t3code 这类项目把 CLI 和 Electron 应用放在同一个仓库里但作为独立的包管理。这样既能共享代码又能独立发布。t3code/ ├── packages/ │ ├── cli/ # CLI 内核独立发布到 npm │ │ ├── bin/ │ │ ├── src/ │ │ └── package.json │ └── desktop/ # Electron 应用 │ ├── main/ │ ├── renderer/ │ ├── preload/ │ └── package.json ├── package.json # 根 package.json用 workspaces └── README.md根目录的package.json里配置workspaces: [packages/*]这样npm install的时候会自动把两个包链接起来desktop 包可以直接require(t3code-cli)而不用先发布。初始化 CLI 包的时候bin字段要指向入口文件并且入口文件顶部要有#!/usr/bin/env node这行 shebang否则全局安装后执行会报错。这个细节很小但新手经常忘。4.2 CLI 内核的功能实现与参数解析CLI 的参数解析我推荐用commander或者yargs不要自己手写process.argv的解析逻辑。手写的话处理--help、--version、子命令、可选参数这些会非常痛苦而且容易出 bug。#!/usr/bin/env node const { program } require(commander); program .name(t3code) .description(t3code 命令行工具) .version(1.0.0); program .command(convert) .description(转换文件格式) .argument(input, 输入文件路径) .option(-o, --output path, 输出路径) .option(-f, --format type, 目标格式, json) .action(async (input, options) { // 实际处理逻辑 console.log(转换 ${input} 为 ${options.format}); }); program.parse();这里有个实操心得CLI 的输出格式要区分给人看和给程序看。默认输出人类可读的文本加一个--json参数输出结构化数据。这样 Electron 壳调用 CLI 时用--json解析起来稳定用户手动敲命令时看默认输出体验好。4.3 Electron 应用的打包配置Electron 打包我用electron-builder它比electron-packager功能全支持自动生成 Mac 的 dmg、Windows 的 nsis 安装包。配置文件放在package.json的build字段或者单独的electron-builder.yml里。关键配置项有几个appId要符合反向域名格式productName是显示名称directories.output指定输出目录。Mac 端如果要签名需要配置mac.identityWindows 端如果要签名配置win.certificateFile。没有签名的话用户安装时会看到安全警告这个体验不太好但个人项目初期可以先跳过。appId: com.example.t3code productName: t3code directories: output: dist files: - main/**/* - renderer/**/* - preload/**/* mac: target: dmg category: public.app-category.developer-tools win: target: nsis注意files字段它决定了哪些文件被打进安装包。CLI 内核如果作为依赖被引用node_modules里的相关文件会自动包含但如果你把 CLI 放在 monorepo 的另一个包里要确保打包时它能被正确解析。4.4 Homebrew 分发的完整流程Mac 端用 Homebrew 分发核心是创建一个 formula 文件。有两种做法一是提交到 homebrew-core但审核严格一般个人项目走不通二是自建 tap也就是一个 GitHub 仓库命名格式是homebrew-xxx。创建 tap 的步骤在 GitHub 上建一个homebrew-t3code仓库里面放Formula/t3code.rb。用户通过brew tap 用户名/t3code添加然后brew install t3code安装。class T3code Formula desc t3code 命令行工具 homepage https://github.com/example/t3code url https://registry.npmjs.org/t3code-cli/-/t3code-cli-1.0.0.tgz sha256 填入实际的 sha256 license MIT depends_on node def install system npm, install, *std_npm_args bin.install_symlink Dir[#{libexec}/bin/*] end end这里有个坑要注意Homebrew 对 macOS 版本有最低要求。热搜词里提到 homebrew取消10.15的支持这是真实发生过的事。如果你的用户里有还在用旧版 macOS 的他们brew install会直接失败。解决办法是在 formula 里不写死depends_on macos:或者提供一个手动安装的备选方案。sha256 的获取方式是下载 tgz 文件后运行shasum -a 256 文件名。每次发新版本都要更新 url 和 sha256手动做很烦可以写个脚本自动生成 formula。4.5 winget 分发的完整流程Windows 端用 winget 分发需要提交 manifest 到microsoft/winget-pkgs仓库。manifest 是一组 YAML 文件通常包含三个版本文件、安装包文件、locale 文件。# 版本文件 PackageIdentifier: Example.t3code PackageVersion: 1.0.0 DefaultLocale: en-US ManifestType: version ManifestVersion: 1.4.0# 安装包文件 PackageIdentifier: Example.t3code PackageVersion: 1.0.0 InstallerType: nullsoft Installers: - Architecture: x64 InstallerUrl: https://github.com/example/t3code/releases/download/v1.0.0/t3code-setup.exe InstallerSha256: 填入实际的 sha256 ManifestType: installer ManifestVersion: 1.4.0提交方式是 forkmicrosoft/winget-pkgs把 manifest 放到manifests/e/Example/t3code/1.0.0/目录下然后提 PR。审核通过后用户就能winget install t3code了。审核一般几天内会有结果比 Homebrew 快。注意winget 的 InstallerSha256 必须和实际文件完全一致一个字符都不能错。我见过有人复制粘贴时多了个空格PR 被打回重来。5. 常见问题与排查技巧实录5.1 安装类问题速查问题现象可能原因排查与解决brew install报 404formula 里的 url 失效检查 npm 包是否已发布url 是否指向正确版本brew install报 sha256 不匹配文件被重新发布或复制错误重新下载文件计算 sha256确保和 formula 一致winget 安装后命令找不到PATH 未刷新重启终端或手动刷新环境变量npm 全局安装后命令找不到npm 全局 bin 目录不在 PATH运行npm config get prefix查看路径加入 PATHMac 安装报无法验证开发者应用未签名系统设置里允许或使用xattr -d com.apple.quarantine5.2 开发调试中的典型坑坑一CLI 子进程输出中文乱码。Windows 上默认编码是 GBKNode.js 输出 UTF-8 时会出现乱码。解决办法是在 spawn 时设置env: { ...process.env, PYTHONIOENCODING: utf-8 }或者在 CLI 入口处显式设置process.stdout.setEncoding(utf8)。坑二Electron 打包后 CLI 路径失效。开发时用__dirname能找到 CLI打包后文件被放到了app.asar里路径变了。解决办法是用process.resourcesPath配合相对路径或者把 CLI 标记为asarUnpack让它解压到磁盘上。坑三Homebrew 卸载残留。brew uninstall只删除 formula 安装的文件但 npm 全局安装的依赖可能残留在libexec目录里。如果用户反馈卸载后还有残留检查 formula 的install方法确保所有文件都在 Homebrew 管理的路径下。坑四winget 更新检测不到新版本。winget 的版本更新依赖 manifest 提交不是自动的。每次发新版都要重新提 PR这点和 Homebrew 一样。可以写个 CI 脚本发 release 时自动生成 manifest 并提 PR省得手动操作。5.3 性能与体验优化技巧CLI 启动速度是个容易被忽视的点。Node.js 启动本身就要一两百毫秒如果 CLI 入口还 require 了一堆重依赖启动会更慢。我的做法是延迟加载入口文件只做参数解析实际功能模块在 action 回调里才 require。这样t3code --help这种常用操作会很快。program .command(convert) .action(async (input, options) { // 只有真正执行时才加载重依赖 const { convert } require(../lib/converter); await convert(input, options); });Electron 应用这边首屏加载速度也很关键。渲染进程的 HTML 要尽量简单复杂界面用懒加载。另外 Electron 的show: false配合ready-to-show事件可以避免白屏闪烁。6. 工具链选型与版本管理经验6.1 Node.js 版本与依赖管理t3code 这类项目对 Node.js 版本有要求因为 Electron 内置的 Node 版本和系统安装的可能不一样。我的建议是在package.json里用engines字段声明最低版本然后在 CI 里用.nvmrc固定开发版本。{ engines: { node: 18.0.0 } }依赖管理上CLI 包的依赖要尽量精简因为用户安装时会下载所有依赖。Electron 包的依赖可以宽松些因为打包时会 bundle 进去。我见过有人 CLI 里引了一堆用不上的包导致安装体积翻了好几倍这种问题在 code review 时要注意。6.2 版本发布与自动化手动发布容易出错尤其是要同时更新 npm、Homebrew formula、winget manifest 三处。我的做法是用 GitHub Actions 做自动化打 tag 时触发 workflow自动发布 npm 包、生成 Homebrew formula 的 PR、生成 winget manifest 的 PR。这套流程搭起来要花点时间但一次投入长期受益。特别是版本多了以后手动更新三处地方漏掉一处就会导致用户装到旧版本。6.3 用户反馈与问题定位CLI 工具出问题时用户往往只给一句报错了没有上下文。我的做法是在 CLI 里加一个--verbose参数输出详细的调试信息同时在错误信息里提示用户加 --verbose 重新运行并附上输出。这样能大幅减少来回沟通的成本。Electron 应用这边可以加一个导出日志的功能把主进程和 CLI 子进程的输出都收集起来用户点一下就能生成一个日志文件。这个功能看起来小但对问题定位帮助很大。7. 我在这类项目上踩过的坑和总结的经验做 t3code 这类跨平台 CLI Electron 项目最大的体会是分发和安装环节花的时间往往比写功能本身还多。功能逻辑可能几天就写完了但让它在 Mac 和 Windows 上都能顺利装上、顺利运行可能要折腾好几周。几个具体的经验第一尽早把分发流程跑通不要等功能全做完才考虑打包。我一般会在项目第一天就搭好 Homebrew tap 和 winget manifest 的骨架哪怕功能还是空的先把能装上这件事验证了。第二跨平台测试一定要在真实机器上做虚拟机里的行为和真机有差异尤其是涉及系统权限和路径的地方。第三错误信息要写清楚用户看不懂的错误等于没有错误信息。还有一个容易被忽视的点卸载体验。很多工具只管装不管卸用户想卸载时发现残留一堆文件。Homebrew 和 winget 都支持卸载但前提是你的安装方式规范。如果安装时往用户目录里乱写文件卸载时就清理不干净。所以从一开始就要规划好文件放哪、配置存哪遵循各平台的习惯。最后说个关于 CLI 和 GUI 平衡的看法。t3code 这类工具的核心价值在 CLIElectron 壳是锦上添花。不要为了做界面而做界面如果某个功能在命令行里一行就能搞定没必要非得在界面上加个按钮。界面的价值在于降低门槛和提供可视化而不是替代命令行。想清楚这一点整个项目的设计方向就不会跑偏。 
长河君 · 2026/10/27 16:14:49 · 阅读 1.2k t3code 跨平台 CLI 工具链：Electron 壳与 Homebrew/winget 分发实战
1. 从 t3code 这个标题说起一个跨平台 CLI 工具链的完整落地思路第一次看到 t3code 这个标题的时候我脑子里蹦出来的第一个念头是这大概率又是一个把命令行工具打包成桌面应用的项目。为什么这么判断因为热搜词里同时出现了 Electron、CLI、Homebrew、winget 这几个关键词这个组合太典型了——它几乎就是用 Electron 做壳把一套 CLI 工具链分发给 Mac 和 Windows 用户的标准配方。我这些年折腾过不少类似的工具从早期的纯脚本分发到后来用 Homebrew Tap 做 Mac 端安装再到用 winget 做 Windows 端分发中间踩的坑能写一本书。t3code 这个项目本质上要解决的问题是如何让一个以命令行交互为核心的工具既能保留 CLI 的高效又能让不熟悉终端的用户通过图形界面用起来同时还要解决跨平台安装和更新的问题。这篇文章我会把 t3code 这类项目的完整实现路径拆开讲。从整体架构怎么设计、Electron 壳和 CLI 内核怎么通信、Homebrew 和 winget 的打包分发怎么做、到实际开发中会遇到哪些坑我都会结合自己的实操经验说清楚。不管你是想自己做一个类似的工具还是想理解这类项目的运作原理或者只是好奇为什么现在这么多 CLI 工具都开始套 Electron 壳这篇内容应该都能给你一些能直接抄作业的东西。适合的读者范围我划一下有基本 Node.js 和命令行使用经验的同学看起来会最顺但如果你是完全的新手我也会把关键概念用生活化的方式解释清楚保证你能跟上。整篇内容会围绕 t3code 这个核心场景展开不会跑偏到无关的技术话题上。2. 整体架构设计为什么是 Electron 加 CLI 的组合2.1 核心需求拆解与方案选型逻辑要理解 t3code 为什么选择 Electron CLI 这个架构得先想清楚它要服务的两类用户。一类是重度终端用户他们希望直接在命令行里敲t3code就能干活追求的是速度和可脚本化另一类是普通用户他们不熟悉终端需要一个能点按钮、看界面的应用。这两类用户的需求看起来是矛盾的但 Electron CLI 的组合恰好能同时满足。具体来说CLI 内核负责所有实际的功能逻辑——文件处理、代码转换、网络请求等等它是纯 Node.js 写的可以独立运行。Electron 壳则是一个图形界面它通过子进程调用 CLI 内核把结果展示在界面上。这样做的好处是核心逻辑只写一遍CLI 用户和 GUI 用户用的是同一套东西不会出现命令行能用但界面报错这种分裂情况。我试过另一种方案就是把逻辑直接写在 Electron 的主进程里然后单独再写一套 CLI。实测下来维护成本翻倍因为任何功能改动都要改两个地方时间一长必然不同步。所以 t3code 选择 CLI 优先、Electron 包装的思路从工程角度看是更稳的。提示CLI 内核和 Electron 壳之间一定要有清晰的边界。我的做法是把 CLI 做成一个独立的 npm 包Electron 只是它的一个消费者。这样即使以后想换掉 Electron 换成 Tauri 或者别的方案CLI 部分完全不用动。2.2 Electron 壳与 CLI 内核的通信机制通信这块是很多人容易搞混的地方。Electron 有主进程main process和渲染进程renderer processCLI 内核跑在哪个进程里直接决定了通信方式。我的建议是CLI 内核作为独立子进程运行通过标准输入输出stdio和主进程通信。为什么不用 Electron 的 IPC 直接调因为 CLI 内核需要能独立运行如果它依赖 Electron 的 IPC 机制那就没法单独当命令行工具用了。用子进程 stdio 的方式CLI 内核完全不知道 Electron 的存在它只是正常地读参数、输出结果。具体实现上主进程用 Node.js 的child_process.spawn启动 CLI然后监听 stdout 和 stderr。渲染进程通过 IPC 把用户操作发给主进程主进程再转发给 CLI 子进程。返回的数据沿着反方向传回去。这套链路听起来绕但每一层职责都很清晰调试的时候也容易定位问题出在哪一环。// 主进程中启动 CLI 子进程的简化示例 const { spawn } require(child_process); const path require(path); function runCli(args, onData, onError) { const cliPath path.join(__dirname, .., cli, bin, t3code.js); const child spawn(node, [cliPath, ...args]); child.stdout.on(data, (data) { onData(data.toString()); }); child.stderr.on(data, (data) { onError(data.toString()); }); child.on(close, (code) { console.log(CLI 进程退出退出码: ${code}); }); return child; }这段代码的关键点在于spawn而不是exec。exec会把所有输出缓冲到内存里输出量大时会出问题spawn是流式的适合处理持续输出的场景。另外注意路径处理打包后 CLI 文件的路径会变用path.join配合__dirname比硬编码路径靠谱得多。2.3 跨平台分发的整体策略分发是 t3code 这类项目最容易被低估的环节。Mac 用户习惯用 HomebrewWindows 用户习惯用 winget如果你只提供一个下载链接让他们手动装转化率会低得可怜。所以 t3code 需要同时维护 Homebrew 的 formula 和 winget 的 manifest。这里有个决策点Electron 应用本身和 CLI 工具是分开分发的还是打包在一起我的做法是分开。CLI 通过 npm 和 Homebrew/winget 分发Electron 应用通过各自的安装包分发。这样 CLI 用户可以只装 CLI不需要下载几百兆的 Electron 运行时。对于只需要命令行功能的用户来说这个体验差别很大。3. 核心细节解析Electron 壳的关键实现要点3.1 主进程与渲染进程的职责划分Electron 的主进程负责窗口管理、菜单、系统集成这些事渲染进程负责界面展示。t3code 这类工具的主进程还需要额外承担一个职责管理 CLI 子进程的生命周期。比如用户关闭窗口时要确保 CLI 子进程也被正确终止否则会留下僵尸进程。我踩过的一个坑是在开发环境下热重载会导致主进程重启但之前启动的 CLI 子进程不会被自动清理。时间一长后台堆了一堆进程把内存吃满了。解决办法是在主进程的before-quit事件里显式杀掉所有子进程。const children new Set(); app.on(before-quit, () { for (const child of children) { if (!child.killed) { child.kill(SIGTERM); } } });渲染进程这边我建议用 preload 脚本做一层安全隔离不要直接开nodeIntegration。虽然 t3code 是本地工具风险相对低但养成好习惯总没错。preload 里通过contextBridge暴露有限的 API 给渲染进程这样即使界面代码有漏洞也不会直接拿到 Node.js 的全部能力。3.2 Electron 菜单与快捷键的设计Electron 的菜单系统在 Mac 和 Windows 上行为差异很大。Mac 有全局菜单栏Windows 是每个窗口一个菜单。t3code 如果要提供新建任务打开配置查看日志这些操作菜单设计得考虑两套逻辑。我的经验是核心操作一定要有快捷键菜单只是辅助。因为 CLI 用户本来就习惯键盘操作给他们一个CmdOrCtrlN新建任务比让他们去菜单里找快得多。Electron 的accelerator字段支持CmdOrCtrl这种跨平台写法Mac 上自动映射成 CmdWindows 上映射成 Ctrl。const template [ { label: 文件, submenu: [ { label: 新建任务, accelerator: CmdOrCtrlN, click: () { mainWindow.webContents.send(menu:new-task); } }, { type: separator }, { label: 退出, accelerator: CmdOrCtrlQ, role: quit } ] } ];注意role: quit这种用法Electron 内置了一批标准角色用 role 比自己写 click 处理更可靠因为它会自动适配平台行为。比如 Mac 上退出是 CmdQWindows 上是 AltF4用 role 就不用自己判断平台了。3.3 本地服务与 localhost 通信的取舍热搜词里出现了 electron localhost这通常是指 Electron 应用在本地起一个 HTTP 服务然后界面通过 localhost 访问。这种模式在某些场景下有用比如需要和浏览器扩展通信或者需要让外部工具调用应用的功能。但对于 t3code 这类工具我的建议是能不用 localhost 就不用。原因有三一是端口冲突问题用户机器上可能已经有别的服务占了那个端口二是安全问题本地服务如果没做好鉴权同机器上的其他程序可以随意调用三是增加了复杂度本来 IPC 能解决的事绕一圈走 HTTP 没必要。如果确实需要本地服务一定要做两件事端口用 0 让系统自动分配然后把实际端口通过 IPC 告诉渲染进程服务只监听 127.0.0.1绝对不要监听 0.0.0.0。4. 实操过程从零搭建 t3code 的完整流程4.1 项目初始化与目录结构设计我一般会用一个 monorepo 的结构来组织 t3code 这类项目把 CLI 和 Electron 应用放在同一个仓库里但作为独立的包管理。这样既能共享代码又能独立发布。t3code/ ├── packages/ │ ├── cli/ # CLI 内核独立发布到 npm │ │ ├── bin/ │ │ ├── src/ │ │ └── package.json │ └── desktop/ # Electron 应用 │ ├── main/ │ ├── renderer/ │ ├── preload/ │ └── package.json ├── package.json # 根 package.json用 workspaces └── README.md根目录的package.json里配置workspaces: [packages/*]这样npm install的时候会自动把两个包链接起来desktop 包可以直接require(t3code-cli)而不用先发布。初始化 CLI 包的时候bin字段要指向入口文件并且入口文件顶部要有#!/usr/bin/env node这行 shebang否则全局安装后执行会报错。这个细节很小但新手经常忘。4.2 CLI 内核的功能实现与参数解析CLI 的参数解析我推荐用commander或者yargs不要自己手写process.argv的解析逻辑。手写的话处理--help、--version、子命令、可选参数这些会非常痛苦而且容易出 bug。#!/usr/bin/env node const { program } require(commander); program .name(t3code) .description(t3code 命令行工具) .version(1.0.0); program .command(convert) .description(转换文件格式) .argument(input, 输入文件路径) .option(-o, --output path, 输出路径) .option(-f, --format type, 目标格式, json) .action(async (input, options) { // 实际处理逻辑 console.log(转换 ${input} 为 ${options.format}); }); program.parse();这里有个实操心得CLI 的输出格式要区分给人看和给程序看。默认输出人类可读的文本加一个--json参数输出结构化数据。这样 Electron 壳调用 CLI 时用--json解析起来稳定用户手动敲命令时看默认输出体验好。4.3 Electron 应用的打包配置Electron 打包我用electron-builder它比electron-packager功能全支持自动生成 Mac 的 dmg、Windows 的 nsis 安装包。配置文件放在package.json的build字段或者单独的electron-builder.yml里。关键配置项有几个appId要符合反向域名格式productName是显示名称directories.output指定输出目录。Mac 端如果要签名需要配置mac.identityWindows 端如果要签名配置win.certificateFile。没有签名的话用户安装时会看到安全警告这个体验不太好但个人项目初期可以先跳过。appId: com.example.t3code productName: t3code directories: output: dist files: - main/**/* - renderer/**/* - preload/**/* mac: target: dmg category: public.app-category.developer-tools win: target: nsis注意files字段它决定了哪些文件被打进安装包。CLI 内核如果作为依赖被引用node_modules里的相关文件会自动包含但如果你把 CLI 放在 monorepo 的另一个包里要确保打包时它能被正确解析。4.4 Homebrew 分发的完整流程Mac 端用 Homebrew 分发核心是创建一个 formula 文件。有两种做法一是提交到 homebrew-core但审核严格一般个人项目走不通二是自建 tap也就是一个 GitHub 仓库命名格式是homebrew-xxx。创建 tap 的步骤在 GitHub 上建一个homebrew-t3code仓库里面放Formula/t3code.rb。用户通过brew tap 用户名/t3code添加然后brew install t3code安装。class T3code Formula desc t3code 命令行工具 homepage https://github.com/example/t3code url https://registry.npmjs.org/t3code-cli/-/t3code-cli-1.0.0.tgz sha256 填入实际的 sha256 license MIT depends_on node def install system npm, install, *std_npm_args bin.install_symlink Dir[#{libexec}/bin/*] end end这里有个坑要注意Homebrew 对 macOS 版本有最低要求。热搜词里提到 homebrew取消10.15的支持这是真实发生过的事。如果你的用户里有还在用旧版 macOS 的他们brew install会直接失败。解决办法是在 formula 里不写死depends_on macos:或者提供一个手动安装的备选方案。sha256 的获取方式是下载 tgz 文件后运行shasum -a 256 文件名。每次发新版本都要更新 url 和 sha256手动做很烦可以写个脚本自动生成 formula。4.5 winget 分发的完整流程Windows 端用 winget 分发需要提交 manifest 到microsoft/winget-pkgs仓库。manifest 是一组 YAML 文件通常包含三个版本文件、安装包文件、locale 文件。# 版本文件 PackageIdentifier: Example.t3code PackageVersion: 1.0.0 DefaultLocale: en-US ManifestType: version ManifestVersion: 1.4.0# 安装包文件 PackageIdentifier: Example.t3code PackageVersion: 1.0.0 InstallerType: nullsoft Installers: - Architecture: x64 InstallerUrl: https://github.com/example/t3code/releases/download/v1.0.0/t3code-setup.exe InstallerSha256: 填入实际的 sha256 ManifestType: installer ManifestVersion: 1.4.0提交方式是 forkmicrosoft/winget-pkgs把 manifest 放到manifests/e/Example/t3code/1.0.0/目录下然后提 PR。审核通过后用户就能winget install t3code了。审核一般几天内会有结果比 Homebrew 快。注意winget 的 InstallerSha256 必须和实际文件完全一致一个字符都不能错。我见过有人复制粘贴时多了个空格PR 被打回重来。5. 常见问题与排查技巧实录5.1 安装类问题速查问题现象可能原因排查与解决brew install报 404formula 里的 url 失效检查 npm 包是否已发布url 是否指向正确版本brew install报 sha256 不匹配文件被重新发布或复制错误重新下载文件计算 sha256确保和 formula 一致winget 安装后命令找不到PATH 未刷新重启终端或手动刷新环境变量npm 全局安装后命令找不到npm 全局 bin 目录不在 PATH运行npm config get prefix查看路径加入 PATHMac 安装报无法验证开发者应用未签名系统设置里允许或使用xattr -d com.apple.quarantine5.2 开发调试中的典型坑坑一CLI 子进程输出中文乱码。Windows 上默认编码是 GBKNode.js 输出 UTF-8 时会出现乱码。解决办法是在 spawn 时设置env: { ...process.env, PYTHONIOENCODING: utf-8 }或者在 CLI 入口处显式设置process.stdout.setEncoding(utf8)。坑二Electron 打包后 CLI 路径失效。开发时用__dirname能找到 CLI打包后文件被放到了app.asar里路径变了。解决办法是用process.resourcesPath配合相对路径或者把 CLI 标记为asarUnpack让它解压到磁盘上。坑三Homebrew 卸载残留。brew uninstall只删除 formula 安装的文件但 npm 全局安装的依赖可能残留在libexec目录里。如果用户反馈卸载后还有残留检查 formula 的install方法确保所有文件都在 Homebrew 管理的路径下。坑四winget 更新检测不到新版本。winget 的版本更新依赖 manifest 提交不是自动的。每次发新版都要重新提 PR这点和 Homebrew 一样。可以写个 CI 脚本发 release 时自动生成 manifest 并提 PR省得手动操作。5.3 性能与体验优化技巧CLI 启动速度是个容易被忽视的点。Node.js 启动本身就要一两百毫秒如果 CLI 入口还 require 了一堆重依赖启动会更慢。我的做法是延迟加载入口文件只做参数解析实际功能模块在 action 回调里才 require。这样t3code --help这种常用操作会很快。program .command(convert) .action(async (input, options) { // 只有真正执行时才加载重依赖 const { convert } require(../lib/converter); await convert(input, options); });Electron 应用这边首屏加载速度也很关键。渲染进程的 HTML 要尽量简单复杂界面用懒加载。另外 Electron 的show: false配合ready-to-show事件可以避免白屏闪烁。6. 工具链选型与版本管理经验6.1 Node.js 版本与依赖管理t3code 这类项目对 Node.js 版本有要求因为 Electron 内置的 Node 版本和系统安装的可能不一样。我的建议是在package.json里用engines字段声明最低版本然后在 CI 里用.nvmrc固定开发版本。{ engines: { node: 18.0.0 } }依赖管理上CLI 包的依赖要尽量精简因为用户安装时会下载所有依赖。Electron 包的依赖可以宽松些因为打包时会 bundle 进去。我见过有人 CLI 里引了一堆用不上的包导致安装体积翻了好几倍这种问题在 code review 时要注意。6.2 版本发布与自动化手动发布容易出错尤其是要同时更新 npm、Homebrew formula、winget manifest 三处。我的做法是用 GitHub Actions 做自动化打 tag 时触发 workflow自动发布 npm 包、生成 Homebrew formula 的 PR、生成 winget manifest 的 PR。这套流程搭起来要花点时间但一次投入长期受益。特别是版本多了以后手动更新三处地方漏掉一处就会导致用户装到旧版本。6.3 用户反馈与问题定位CLI 工具出问题时用户往往只给一句报错了没有上下文。我的做法是在 CLI 里加一个--verbose参数输出详细的调试信息同时在错误信息里提示用户加 --verbose 重新运行并附上输出。这样能大幅减少来回沟通的成本。Electron 应用这边可以加一个导出日志的功能把主进程和 CLI 子进程的输出都收集起来用户点一下就能生成一个日志文件。这个功能看起来小但对问题定位帮助很大。7. 我在这类项目上踩过的坑和总结的经验做 t3code 这类跨平台 CLI Electron 项目最大的体会是分发和安装环节花的时间往往比写功能本身还多。功能逻辑可能几天就写完了但让它在 Mac 和 Windows 上都能顺利装上、顺利运行可能要折腾好几周。几个具体的经验第一尽早把分发流程跑通不要等功能全做完才考虑打包。我一般会在项目第一天就搭好 Homebrew tap 和 winget manifest 的骨架哪怕功能还是空的先把能装上这件事验证了。第二跨平台测试一定要在真实机器上做虚拟机里的行为和真机有差异尤其是涉及系统权限和路径的地方。第三错误信息要写清楚用户看不懂的错误等于没有错误信息。还有一个容易被忽视的点卸载体验。很多工具只管装不管卸用户想卸载时发现残留一堆文件。Homebrew 和 winget 都支持卸载但前提是你的安装方式规范。如果安装时往用户目录里乱写文件卸载时就清理不干净。所以从一开始就要规划好文件放哪、配置存哪遵循各平台的习惯。最后说个关于 CLI 和 GUI 平衡的看法。t3code 这类工具的核心价值在 CLIElectron 壳是锦上添花。不要为了做界面而做界面如果某个功能在命令行里一行就能搞定没必要非得在界面上加个按钮。界面的价值在于降低门槛和提供可视化而不是替代命令行。想清楚这一点整个项目的设计方向就不会跑偏。