Bruno 跨平台工程实践：Electron 应用在 macOS、Windows 与 Linux 上的文件系统、进程与路径处理指南

本文基于 Bruno 仓库中的跨平台开发规范文档 .claude/rules/cross-platform.md 展开，系统讲解一个同时面向 macOS、Windows 和 Linux 的 Electron 桌面应用（Bruno，一个用于探索和测试 API 的开源 IDE）在文件系统删除与路径比较、子进程管理、信号与退出流程、换行符解析、输出流差异、平台原生依赖安装以及工作区路径持久化等方面必须遵守的工程准则。读完后，你将掌握在 Bruno 这类跨平台项目中排查路径不一致、进程残留、Windows 删除失败等典型问题的方法，并能从源码层面理解每条规范背后的实现依据。

该规范文档以 Agent 规则文件（.claude/rules）的形式存放，其 frontmatter 声明了作用域：scripts/**/* 与 packages/bruno-electron/**/*——也就是说，凡涉及这两个路径下文件系统的代码（包括 Electron 主进程与构建/安装脚本），都必须满足三平台（macOS、Windows、Linux）可运行这一底线。

一、文件系统：删除、路径与监视器

跨平台代码在文件系统层面最容易踩坑。规范文档对 Bruno 提出了以下硬性要求，仓库源码中均能找到对应实现。

1.1 fs.rmSync 的 force: true 只吞掉 ENOENT

fs.rmSync 的 force: true 选项仅能抑制 ENOENT（目标不存在）错误，不能抑制 EPERM/EBUSY（权限错误/文件被占用）。Windows 对文件加锁非常激进——杀毒软件、系统索引服务、未释放的文件句柄都会让目录删除失败。因此规范要求在删除目录时始终配合 maxRetries 与 retryDelay 使用重试机制。

仓库中 scripts/setup.js 的初始化流程就依赖目录清理逻辑：它在安装依赖前先清理各包下的 node_modules（见 setup 脚本 中 setup() 函数里 fs.rmSync(dir, { recursive: true, force: true }) 的调用）。这类清理代码在 Windows 开发机上遇到 EBUSY 时，就是规范要求重试参数的典型场景。

1.2 路径拼接一律走 path 模块，禁止硬编码 /

所有路径必须使用 path.join() / path.resolve() 构造，严禁在字符串里硬编码 / 分隔符。Bruno 更进一步做了一层抽象：渲染进程侧的路径工具 utils/common/path.js 在模块加载时按操作系统选择 path.win32 或 path.posix：

// packages/bruno-app/src/utils/common/path.js
const brunoPath = isWindowsOS() ? path.win32 : path.posix;

其中 isWindowsOS() 通过 platform 库判断操作系统家族。该文件还实现了 getRelativePath、getAbsoluteFilePath、getRelativePathWithinBasePath、isPathExternalToBasePath 等一整套跨平台路径计算函数，函数签名中普遍带有 shouldPosixify 参数——这正是下一节要讲的"路径 POSIX 化"策略，其注释（path.js 顶部文档块）明确解释了动机：bruno.json 中的相对路径会被提交进版本控制，Windows 用户写的 certs\\client.pem 在 Unix 上无法解析，因此统一存储为正斜杠格式（Windows 原生支持 / 作为分隔符），从而消除跨平台协作时的人工路径转换。

1.3 Windows 路径不区分大小写：用 normalizePath() 比较

由于 Windows 文件系统路径大小写不敏感，直接 === 比较两个 collection/workspace 路径可能在"实际指向同一目录"时误判为不同。规范要求：比较集合/工作区路径前，先经过 normalizePath() 归一化。源码实现非常简洁（path.js#L216-L219）：

const normalizePath = (p) => {
  if (!p) return '';
  return p.replace(/\\/g, '/').replace(/\/+$/, '');
};

即：反斜杠统一替换为正斜杠、去掉末尾多余斜杠。该函数被广泛复用于快照序列化、集合操作、工作区切片等模块（如 snapshot/serializeSnapshot.js、collections/actions.js），保证比较基准一致。

1.4 不要假设 POSIX 风格的系统目录

app.getPath() 返回的是平台特定目录（userData、documents 等）。macOS 是 ~/Library/Application Support/...，Windows 是 %APPDATA%/...，Linux 是 ~/.config/...。代码中绝不能写死任何 POSIX 风格位置。这一约束在 Electron 主进程入口 有体现：开发模式下若设置了 ELECTRON_USER_DATA_PATH，通过 app.setPath('userData', ...) 整体重定向，而不是拼接具体目录。

1.5 chokidar 事件顺序不跨平台保证

文件监视器（chokidar）在不同平台上发出的事件顺序可能不同。规范明确要求：不要依赖特定的 add/change/unlink 事件序列。Bruno 在 Electron 主进程中同时运行了三个监视器——集合监视器 collection-watcher.js、工作区监视器 workspace-watcher.js、API 规范监视器 apiSpecsWatcher.js——它们的实现都只以"最终状态正确"为目标，而非依赖事件到达顺序。

二、子进程：spawn、kill 与命令语法

2.1 在 Windows 上 spawn npm 必须加 shell: true

Windows 上的 npm 实际是 npm.cmd 批处理包装器，spawn('npm', [...]) 不启用 shell 时无法定位到它，因此规范要求 spawn('npm', [...]) 在 Windows 上必须带 shell: true。

2.2 child.kill() 杀不掉进程树，Windows 上要用 taskkill

shell: true 时，child.kill() 只能杀死 shell 包装层（Windows 上是 cmd.exe），真正的子进程会变成孤儿进程继续运行。规范给出的解法是用 taskkill /pid <pid> /T /F 递归杀死整个进程树（/T 表示含子进程，/F 表示强制）。

仓库的测试基建中就有同类用法：SSL 测试的辅助服务器在端口清理逻辑里直接调用 taskkill /F /PID <pid> 终止进程（见 tests/ssl/client-certs/server/helpers/platform.js#L86 与 tests/ssl/custom-ca-certs/server/helpers/platform.js#L47），并且注释中专门解释了原因——kill/taskkill 只是向内核请求终止进程，端口可能仍处于短暂绑定状态，需要配合重试。

2.3 命令语法要避开 Unix 专属写法

execSync / spawn 中不应使用 Unix 专属语法。规范特别指出：&& 链在 cmd.exe 中恰好可用，但管道与重定向行为与 shell 存在差异。从源码结构看，Bruno 的构建脚本（如 scripts/setup.js）选择逐条调用 execCommand('npm i --legacy-peer-deps', ...)、npm run build:* 而不是用 shell 链式命令，正是规避这类语法差异的做法。

三、信号与关闭流程

3.1 Windows 上 SIGINT/SIGTERM 不可靠

SIGINT / SIGTERM 在 Windows 上（尤其 shell: true 场景）不可靠，规范建议同时处理 SIGHUP 作为兜底。

3.2 应用退出必须关闭所有文件监视器

这是规范中最有实现深度的一条。Bruno 的每个 watcher 类都实现了 closeAllWatchers() 方法，由主进程入口统一编排（index.js#L132-L135）：

const closeAllWatchers = () => Promise.allSettled([
  collectionWatcher.closeAllWatchers(),
  workspaceWatcher.closeAllWatchers(),
  apiSpecWatcher.closeAllWatchers()
]);

退出路径的处理在 before-quit 事件中（index.js#L540-L556）：先 event.preventDefault() 延迟真正退出，然后用 Promise.race 给 closeAllWatchers() 加上 2000 毫秒的超时上限，再依次完成挂载点卸载、SQLite 关闭、单实例锁释放、Cookie 存储落盘和终端进程清理。源码注释解释了这样做的必要性：chokidar 的 fsevents 句柄清理是异步的，若主进程在清理途中退出，Chromium 辅助进程会检测到断裂的 IPC 通道而 abort()，最终触发 macOS 的 "quit unexpectedly" 弹窗。这正是"信号与关闭"规范在真实代码中的完整落地——关闭顺序、超时保护、异步收尾三要素缺一不可。

四、换行符：CRLF 感知的解析

Windows 创建的文件使用 CRLF 换行。规范明确指出：逐行解析多行 .bru/文本块时，必须用 CRLF 感知的正则 /\r\n|\r|\n/ 拆分，绝不能只按 \n 拆——否则行尾会残留一个 \r，污染解析结果，进而引发"虚假的 dirty 状态"和 diff 噪声。

规范指定的参考模式（reference pattern）是 bruno-lang v2 的 envToJson.js 中对多行文本块的解析：

multilinetextblock(_1, content, _2) {
  return content.ast
    .split(/\r\n|\r|\n/)
    .map((line) => line.slice(indentLevel)) // Remove 4-space indentation
    .join('\n')
    .trim();
}

注意这里先按 /\r\n|\r|\n/ 拆分、再统一以 \n 重组，等效于把 Windows CRLF 归一化为 LF。这一模式在 bruno-lang v2 解析器中保持一致：collectionBruToJson.js#L276、example/jsonToBru.js#L23 以及 utils.js 中多处都使用了同样的拆分正则。规范还要求新写的解析器保持与该模式一致。

测试侧也有对应保障：jsonToBru.spec.js#L323 的注释直接说明了行为——indentString splits on \r\n|\r|\n and rejoins with \n, normalizing Windows CRLF to LF。

五、stdout 与 stderr：输出检测要双流检查

开发工具（rsbuild、webpack、electron-builder）在 Windows 上可能把启动期输出路由到 stderr。因此，凡是通过"匹配进程输出中的模式"来判断构建/启动状态的地方，必须同时检查 stdout 和 stderr 两个流，否则会漏掉关键信息、误判进程状态。对 Bruno 这样依赖多阶段 npm run build:* 链（见 setup.js）的项目，这条规则直接影响 CI 与本地构建脚本的健壮性。

六、平台特定依赖的安装

6.1 forceInstallPlatformDeps() 强制安装原生模块

scripts/setup.js#L68-L85 中的 forceInstallPlatformDeps() 是这条规范的直接实现：它维护了一张按 process.platform 索引的依赖表，为 darwin、win32、linux 各平台列出对应架构（arm64/x64）的 @lydell/node-pty-{platform}-{arch}@1.1.0 原生模块，然后以 npm i --legacy-peer-deps --no-save --force 强制安装。注释特别强调两点：依赖必须硬锁定版本，且只添加已经做过安全漏洞核查的包——因为 --force 安装绕过了正常的依赖解析。

6.2 打包配置按平台分支

Electron 的打包配置 electron-builder-config.js 按 mac / win / linux 目标分别处理平台特定的打包项，与文档中 "Electron builder config handles platform-specific packaging" 的描述一致。

七、Collection/Workspace 存储中的路径分隔符

这一节解释了 Bruno 存储层的一个固有现象：

• electron-store 按原样持久化路径。同一工作区在 macOS 上打开存的是 /Users/...，在 Windows 上打开存的是 C:\Users\...。因此任何跨会话、跨平台读取这些存储路径的代码，都不能假设分隔符风格统一——结合第一节，正确做法是先 normalizePath() 再比较。
• ELECTRON_USER_DATA_PATH 仅在开发模式生效。主进程入口 index.js#L21-L26 的条件是 isDev && process.env.ELECTRON_USER_DATA_PATH（规范文档引用为 index.js:22），即该环境变量只对开发构建生效，打包后的应用会走默认 userData 路径。做跨环境测试或数据迁移时需要注意这一前提。

此外，与"存储路径进版本控制"相关的是 utils/common/path.js 的 posixify 策略：bruno.json 等提交到 git 的配置文件中，客户端证书、protobuf 文件等相对路径统一以正斜杠存储（posixify(str) 即 str.replace(/\\/g, '/')），Windows 原生兼容正斜杠，从而避免提交前手工转换路径，也减少与 git 冲突相关的合并问题。

小结：把规范映射到代码

.claude/rules/cross-platform.md 的每一条规则都能在 Bruno 仓库中找到对应的实现或测试证据，归纳如下：

规范条目	仓库中的实现/佐证
rmSync 删除需重试	scripts/setup.js 的 node_modules 清理流程
路径比较用 normalizePath()	packages/bruno-app/src/utils/common/path.js#L216-L219，被快照、集合、工作区模块复用
spawn npm 需 shell: true、taskkill 杀进程树	tests/ssl/client-certs/server/helpers/platform.js#L86 等平台辅助代码
退出时关闭所有 watcher	packages/bruno-electron/src/index.js#L132-L135 与 before-quit 处理
CRLF 感知拆行	packages/bruno-lang/v2/src/envToJson.js#L276-L282，测试见 jsonToBru.spec.js#L323
平台原生依赖强装	scripts/setup.js#L68-L85 forceInstallPlatformDeps()
存储路径按原样持久化、ELECTRON_USER_DATA_PATH 仅 isDev 生效	packages/bruno-electron/src/index.js#L21-L26

这套规范的价值在于：它不是抽象的"跨平台建议"，而是每一条都锚定到 Bruno 的具体模块（Electron 主进程、bruno-lang 解析器、安装脚本、测试基建），既约束人类开发者，也约束 AI 代理在 scripts/ 与 packages/bruno-electron/ 下生成代码时的行为边界。