1. 从“t3code”这个名字说起它到底想解决什么问题第一次看到“t3code”这个标题加上关键词里那一串 Electron、CLI、Homebrew、winget我脑子里第一反应是这大概率是一个把本地开发工具链打包成桌面应用、同时提供命令行入口的项目。为什么这么判断因为 Electron 负责跨平台桌面壳CLI 负责终端里的自动化调用Homebrew 和 winget 分别对应 macOS 和 Windows 的包管理分发——这三样东西凑在一起基本就是“一个工具两种用法三端安装”的典型组合。但这里有个容易被忽略的点很多人做 Electron 项目做着做着就变成了“只会双击图标”的 GUI 工具命令行能力完全缺失反过来很多 CLI 工具想加个图形界面又得重新写一套 UI维护成本直接翻倍。t3code 这个标题背后我理解的核心诉求是同一套核心逻辑既能被 Electron 主进程调用也能被终端里的 CLI 调用还能通过 Homebrew 和 winget 让用户一条命令装好。这听起来简单实际做起来坑非常多尤其是 Electron 的打包体积、CLI 的路径解析、以及两个包管理器对“可执行文件”的不同要求。我之所以对这个方向感兴趣是因为过去两年我参与过三个类似形态的项目一个是内部用的代码片段管理器一个是 API 调试工具还有一个是本地模型启动器。这三个项目都踩过“GUI 和 CLI 共用逻辑”的坑也都在 Homebrew 和 winget 的分发上花过不少时间。所以下面这些内容不是纸上谈兵而是我实际趟出来的经验。如果你正在做类似 t3code 这样的工具或者你只是好奇“为什么一个 Electron 应用还要搞 CLI”那这篇内容应该能帮你省下不少试错成本。我会从架构拆分、CLI 入口设计、Homebrew 打包、winget 提交、以及 Electron 本身的打包优化这几个角度把整个链路拆开讲清楚。每个部分我都会解释“为什么这么做”而不是只给一堆命令让你抄。2. 把 Electron 和 CLI 拆成两个入口架构上的取舍2.1 为什么不能把 CLI 逻辑直接塞进 Electron 主进程很多人第一版会这么干在 Electron 的 main 进程里写一堆业务逻辑然后 CLI 入口直接require那个 main 文件。结果一运行就报错因为 Electron 的 main 进程依赖app、BrowserWindow这些模块在纯 Node 环境下根本不存在。更麻烦的是Electron 打包后的可执行文件是一个完整的 Chromium 壳你没法在终端里直接调用它内部的某个函数。正确的做法是把核心逻辑抽成一个独立的 Node 包Electron 和 CLI 都作为它的消费者。这个包不依赖任何 Electron API只依赖 Node 标准库和少量纯 JS 依赖。目录结构大概是这样t3code/ packages/ core/ # 纯 Node 逻辑无 Electron 依赖 src/ index.js parser.js runner.js cli/ # 命令行入口依赖 core bin/ t3code.js package.json desktop/ # Electron 应用依赖 core main.js renderer/ package.json这样做的好处是CLI 包可以单独发布到 npm用户npm install -g就能用Electron 包可以单独打包成 dmg 或 exe两者共享同一套业务逻辑改一处两边都生效。坏处是构建流程变复杂了需要用到 monorepo 工具比如 pnpm workspace 或者 npm workspaces。我实测下来pnpm workspace 在处理这种“一个 core 被两个包引用”的场景时最顺手因为它的符号链接机制不会把 core 复制两份。npm workspaces 也能用但在 Windows 上偶尔会出现路径解析问题尤其是当 CLI 包需要读取 core 包里的资源文件时。2.2 CLI 入口的 shebang 和路径解析陷阱CLI 包的核心是bin/t3code.js文件第一行必须是#!/usr/bin/env node这行 shebang 决定了这个文件被当作 Node 脚本执行。但这里有个坑如果你在 Windows 上开发用npm link测试时shebang 可能不生效因为 Windows 不认#!。解决办法是在package.json里配置bin字段{ name: t3code-cli, bin: { t3code: ./bin/t3code.js } }这样 npm 在安装时会自动生成一个.cmd包装器Windows 用户也能直接用t3code命令。但要注意这个.cmd文件里会写死 Node 的路径如果用户换了 Node 版本可能会失效。所以更稳妥的方式是让用户通过 Homebrew 或 winget 安装由包管理器来处理 Node 依赖。另一个坑是路径解析。CLI 运行时process.cwd()是用户当前所在目录而不是 CLI 脚本所在目录。如果你需要读取 core 包里的配置文件不能用相对路径./config.json而要用const path require(path); const configPath path.join(__dirname, .., config.json);__dirname在 CommonJS 里指向当前脚本所在目录这样无论用户在哪运行都能找到正确文件。如果你用 ESM那就得用import.meta.url配合fileURLToPath稍微麻烦一点。2.3 Electron 主进程如何调用 core 逻辑Electron 的 main 进程本质上也是一个 Node 环境所以它可以直接require(t3code-core)。但要注意Electron 打包后node_modules会被塞进app.asar里而 asar 是一个只读归档文件。如果你的 core 逻辑需要写临时文件不能写到__dirname下面必须写到app.getPath(userData)返回的目录。我踩过的一个坑是core 包里用了fs.writeFileSync(./cache.json)在开发环境下没问题因为当前目录可写但打包后当前目录变成了 asar 内部直接报EROFS: read-only file system。后来改成把缓存路径作为参数传入Electron 传userData路径CLI 传os.tmpdir()路径问题才解决。所以架构拆分的原则是core 包只负责纯逻辑所有涉及文件系统、网络、环境变量的操作都通过参数注入。这样 Electron 和 CLI 可以各自决定用哪个目录、哪个网络代理、哪个环境变量core 本身保持无状态。3. Homebrew 分发从 Formula 到 Cask 的选择3.1 为什么 CLI 工具优先用 Formula 而不是 CaskHomebrew 有两种包类型Formula 和 Cask。Formula 通常用于命令行工具和库Cask 用于图形界面应用。t3code 如果同时提供 CLI 和 Electron 桌面应用理论上可以两个都发CLI 走 Formula桌面应用走 Cask。但这里有个现实问题Homebrew 对 Cask 的审核越来越严尤其是 Electron 应用因为体积大、更新频繁很多维护者不愿意接。而 Formula 相对宽松只要你的工具能通过命令行安装和运行基本都能过。我建议的策略是先发 CLI 的 Formula等用户量起来了再考虑 Cask。CLI 的 Formula 写起来也简单一个 Ruby 文件就够了class T3code Formula desc A tool for t3code workflows homepage https://example.com/t3code url https://registry.npmjs.org/t3code-cli/-/t3code-cli-1.0.0.tgz sha256 abc123... license MIT depends_on node def install system npm, install, *std_npm_args bin.install_symlink Dir[#{libexec}/bin/*] end end这个 Formula 的核心逻辑是下载 npm 包用 npm 安装到 Homebrew 的 libexec 目录然后把可执行文件链接到 bin 目录。std_npm_args是 Homebrew 提供的一个辅助方法会自动处理 npm 的安装路径和缓存。3.2 Homebrew 取消 10.15 支持带来的连锁反应最近 Homebrew 宣布取消对 macOS 10.15 的支持这意味着如果你的用户还在用 Catalina他们无法通过 Homebrew 安装最新版的 t3code。这个影响比想象中大因为很多开发者的老机器还停留在 10.15。应对方案有两个一是提供一个独立的安装脚本不依赖 Homebrew直接下载预编译的二进制文件二是在 Formula 里声明depends_on macos: :big_sur让 Homebrew 在旧系统上直接报错而不是安装后运行失败。我倾向于第一种方案因为 CLI 工具本身不大预编译一个 Node 单文件可执行程序用pkg或nexe并不难。用户下载后chmod x就能用不需要 Node 环境也不需要 Homebrew。这样既绕开了系统版本限制也减少了依赖冲突。但预编译也有代价pkg打包后的文件体积会膨胀到 40MB 以上因为要把 Node 运行时塞进去。如果你的 CLI 逻辑不复杂可以考虑用bun build --compile打出来的文件更小启动也更快。不过 bun 的兼容性还需要验证尤其是涉及原生模块的时候。3.3 Homebrew 卸载残留为什么你的工具删不干净Homebrew 卸载 Formula 时只会删除它自己安装的文件不会动用户在~/.t3code或~/Library/Application Support/t3code下生成的数据。这是设计如此但对用户来说卸载后残留一堆缓存文件体验很差。解决办法是在 Formula 里加一个zap块def zap rm_rf #{Dir.home}/.t3code rm_rf #{Dir.home}/Library/Application Support/t3code end用户执行brew uninstall --zap t3code时这些目录会被一并删除。但要注意zap是破坏性操作一定要在文档里写清楚避免用户误删重要数据。另外如果你的 CLI 在运行时会写日志到/tmpHomebrew 不会管这些文件需要你在 CLI 启动时自己清理过期日志。我的做法是每次启动时检查日志目录删除 7 天前的文件这样既不会积累太多也不会误删最近的调试信息。4. winget 提交Windows 分发的那些坑4.1 winget 的 manifest 结构比想象中复杂winget 的包描述文件叫 manifest一个完整的 manifest 包含三个 YAML 文件版本文件、安装程序文件、区域设置文件。很多人以为写一个就够了结果提交时被拒。版本文件t3code.yaml大概长这样PackageIdentifier: Example.T3code PackageVersion: 1.0.0 PackageLocale: en-US Publisher: Example PackageName: t3code License: MIT ShortDescription: A tool for t3code workflows Installers: - Architecture: x64 InstallerType: nullsoft InstallerUrl: https://example.com/t3code-setup.exe InstallerSha256: abc123... ManifestType: singleton ManifestVersion: 1.4.0注意InstallerType必须和你的安装包类型匹配。Electron 应用通常用nullsoftNSIS或wixMSI。如果你用 electron-builder 打包默认生成的是 NSIS 安装包所以填nullsoft。InstallerSha256是安装包的哈希值每次发版都要更新。我建议在 CI 里自动计算并替换避免手动填错。4.2 为什么你的 winget 提交总是被拒winget 的审核团队对几个点特别敏感一是安装包必须能静默安装二是安装后必须能在“应用和功能”里看到三是卸载必须干净。很多 Electron 应用栽在第一条上因为默认的 NSIS 安装包会弹出 UI需要用户点“下一步”。解决办法是在 electron-builder 的配置里加上{ nsis: { oneClick: false, allowToChangeInstallationDirectory: true, perMachine: false, deleteAppDataOnUninstall: true } }oneClick: false会让安装包显示界面但 winget 要求静默安装所以还需要在 manifest 里加InstallerSwitchesInstallerSwitches: Silent: /S SilentWithProgress: /S/S是 NSIS 的静默安装参数。加上这个之后winget 安装时就不会弹窗了。另一个常见拒因是Publisher和PackageName不符合规范。Publisher必须是公司或个人名称不能是网址PackageName不能包含版本号或特殊字符。我见过有人填Publisher: example.com直接被拒。4.3 winget 和 Homebrew 的版本同步问题如果你同时维护 Homebrew 和 winget 两个渠道最大的痛点是版本同步。Homebrew 的 Formula 更新需要提 PR 到 homebrew-core审核周期可能几天winget 的 manifest 更新也要提 PR审核周期类似。如果两个渠道的版本不一致用户在不同平台装到的功能可能不一样。我的做法是用 GitHub Actions 自动提 PR。每次发版时CI 自动生成 Homebrew Formula 和 winget manifest然后分别向两个仓库提 PR。这样至少保证提交时间一致剩下的就是等审核。但要注意Homebrew 对 Formula 的sha256校验很严格如果 npm 包的 tarball 重新发布过哈希值会变导致安装失败。所以发版后不要重新发布同一个版本的 npm 包哪怕只是改了个 README。5. Electron 打包优化体积、启动速度和 localhost 问题5.1 Electron 打包 apk 的可行性分析关键词里出现了“electron打包apk”我猜有人想把这个工具搬到 Android 上。技术上可行但体验很差。Electron 本身不支持 Android需要用electron-forge的 Android 模板或者Capacitor这类桥接方案。打出来的 apk 体积至少 80MB 起步启动速度也比原生慢很多。如果你的核心逻辑是纯 Node 的更好的方案是用Termux在 Android 上跑 CLI而不是打包成 apk。Termux 是一个 Android 终端模拟器支持安装 Node 和 npm用户可以直接npm install -g t3code-cli。这样既不用重新打包也不用担心 UI 适配。当然如果你非要 apk那就得接受体积和性能的妥协。我试过用 Capacitor 包装一个 Electron 应用结果发现很多 Node 原生模块在 Android 上根本编译不过最后只能把核心逻辑用 JS 重写一遍。5.2 Electron localhost 加载失败的排查思路Electron 开发时经常遇到localhost加载失败的问题尤其是用 Vite 或 Webpack Dev Server 的时候。常见原因有三个一是端口被占用二是 Dev Server 没启动三是 Electron 的loadURL时机不对。排查步骤我一般是这样先在浏览器里打开http://localhost:5173确认 Dev Server 正常。检查 Electron 主进程的loadURL是否在app.whenReady()之后调用。如果用了wait-on确认等待的端口和实际端口一致。检查是否有代理设置干扰Electron 默认会读取系统代理。我踩过最坑的一次是Dev Server 启动在127.0.0.1但 Electron 的loadURL写的是localhost在某些系统上localhost解析到::1IPv6导致连接失败。改成127.0.0.1就好了。5.3 Electron 菜单的跨平台差异Electron 的菜单在 macOS 和 Windows 上行为完全不同。macOS 的菜单栏在屏幕顶部Windows 的菜单在窗口内部。如果你用同一套菜单模板macOS 上会出现“应用名”菜单重复的问题。正确的做法是根据平台动态生成菜单const { app, Menu } require(electron); const template [ ...(process.platform darwin ? [{ label: app.name, submenu: [ { role: about }, { type: separator }, { role: quit } ] }] : []), { label: File, submenu: [ { role: open }, { role: save } ] } ]; Menu.setApplicationMenu(Menu.buildFromTemplate(template));这样 macOS 上会多一个应用名菜单Windows 上则没有。另外macOS 的role: quit会自动绑定CmdQWindows 上则需要手动加accelerator。6. 实操心得那些文档里不会写的细节6.1 Node 安装 codex cli 很慢的解决办法关键词里有人提到“node安装codex cli很慢”这其实和 npm 的 registry 有关。默认的registry.npmjs.org在国内访问确实慢但我不建议直接换第三方镜像因为有些镜像同步不及时会导致装到旧版本。我的做法是用 npm 的--prefer-offline配合本地缓存。第一次安装时慢就慢点之后只要缓存没清重装就很快。另外如果你的项目依赖很多可以用pnpm代替npmpnpm 的硬链接机制在重复安装时优势明显。还有一个技巧是把node_modules打包进 Docker 镜像CI 里直接复用避免每次重新安装。但这对本地开发帮助不大。6.2 codex cli 没有可用终端或文件读取工具的排查这个报错通常是因为 CLI 运行在一个受限环境里比如 CI 容器或者没有 TTY 的终端。Node 的process.stdin.isTTY会返回false导致依赖交互式输入的功能失效。解决办法是给 CLI 加一个--no-interactive参数让它在非 TTY 环境下自动跳过交互步骤。另外文件读取工具报错可能是因为权限问题检查一下 CLI 是否有权限读取目标目录。我遇到过一次是 Docker 容器里没有/dev/tty导致readline模块直接崩溃。后来改成用process.stdin的data事件手动读取才绕过这个问题。6.3 Homebrew 安装失败的常见原因macOS 上 Homebrew 安装失败十有八九是网络问题或者权限问题。网络问题表现为curl: (7) Failed to connect权限问题表现为Permission denied dir_s_mkdir。权限问题的解决办法是sudo chown -R $(whoami) /usr/local/Homebrew sudo chown -R $(whoami) /usr/local/Cellar但更推荐的做法是不要用sudo安装 Homebrew而是装到用户目录下mkdir -p ~/homebrew curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C ~/homebrew然后把~/homebrew/bin加到PATH里。这样完全不需要sudo也不会污染系统目录。6.4 删除 codex cli 指令的正确姿势如果你用 npm 全局安装了 CLI卸载时用npm uninstall -g t3code-cli但有时候 npm 会留下一些残留文件尤其是 bin 目录下的符号链接。手动检查一下which t3code ls -la $(npm root -g)/t3code-cli如果which t3code还能找到说明符号链接没删干净手动rm掉即可。如果你用 Homebrew 安装的卸载时用brew uninstall t3code brew cleanupbrew cleanup会删除旧版本的缓存文件释放磁盘空间。7. 关于 t3code 后续扩展的一些想法这个项目如果继续做下去我觉得有几个方向值得尝试。一是把 core 包做成 WASM这样浏览器里也能跑同一套逻辑Electron 的渲染进程可以直接调用不需要通过 IPC 绕一圈。二是给 CLI 加一个--json输出模式方便其他工具集成比如 CI 里解析结果。三是把 Homebrew 和 winget 的发布流程完全自动化用 GitHub Actions 监听 tag自动提 PR减少手动操作。不过这些都是后话先把核心链路跑通再说。我在实际做类似项目时最大的体会是不要一开始就追求三端同步发布先把 CLI 做稳定再考虑 Electron 和包管理器。因为 CLI 的反馈周期最短改一行代码就能测试而 Electron 打包一次要几分钟Homebrew 提 PR 要等审核节奏完全不一样。另外如果你也在做类似 t3code 这样的工具建议尽早把 core 包单独发到 npm哪怕功能还不完整。这样别人可以npm install你的 core 包基于它做二次开发你也能从社区反馈里发现哪些 API 设计得不合理。闭门造车做出来的接口往往和实际使用场景差得很远。