Bruno 开源仓库贡献开发实战指南：从本地环境搭建、npm workspaces 构建到提交流程

Bruno 开源仓库贡献开发实战指南从本地环境搭建、npm workspaces 构建到提交流程【免费下载链接】brunoOpensource IDE For Exploring and Testing APIs (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/bruno导读本文依据 docs/contributing/contributing_ua.md乌克兰语贡献指南梳理 Bruno——一款开源、离线的 API 探索与测试 IDE——的源码贡献开发全流程。你将学会识别项目的技术栈与 monorepo 结构、在本地以双进程模式启动桌面应用Web/UI 进程 Electron 主进程、处理npm install常见的Unsupported platform报错、按 npm workspaces 定向或全量运行测试并遵循仓库要求的小型化 PR 与分支命名规范提交代码。文中所有命令均与仓库根目录 package.json、.nvmrc 等实际配置相互印证可直接照做。Bruno 的工程架构与依赖环境技术栈速览按照 contributing_ua.md 的说明Bruno 桌面版由两套运行时共同构成基于 React 构建的用户界面以及用于承载「本地集合」能力在文件系统上直接读写集合的 Electron 桌面壳。文档明确列出的关键库如下关注点采用库CSS 样式Tailwind代码编辑器Codemirror状态管理Redux图标Tabler Icons表单formikSchema 校验Yup请求客户端axios文件系统监听chokidar对照仓库源码可以印证这些选型在代码中的真实落点packages/bruno-app/package.json 中实际声明了reduxjs/toolkit、codemirror、tabler/icons、formik、yup等依赖且 UI 构建工具是rsbuilddev: rsbuild devpackages/bruno-electron/package.json 中则能看到axios、chokidar等运行于主进程/桌面环境的依赖它们服务于文件监听、本地存储与网络请求执行。需要提醒的是贡献文档撰写时间较早其中基于 Next.js的描述在当下仓库中已演进为 rsbuild 驱动的 React 应用可参见根 contributing.md 的说明技术栈细节请以仓库内各package.json的实际依赖清单为最终依据。工具链版本要求文档要求使用Node.js 及 npm并且特别强调本项目是npm workspaces工作区结构的 monorepo。这一点在根 package.json 中得到确认仓库共声明了bruno-app、bruno-electron、bruno-cli、bruno-common、bruno-converters、bruno-schema、bruno-query、bruno-js、bruno-lang、bruno-graphql-docs、bruno-requests、bruno-filestore、bruno-sqlite等十余个工作区包。关于 Node 具体版本号文档与当前仓库存在差异实操时应以仓库为准贡献文档中先后出现过Node v20.x/LTS与NodeJS v18的说法仓库根目录的 .nvmrc 目前固定为v22.12.0因此无论文档如何描述建议统一遵循.nvmrc。这也是文档让开发者先执行nvm use的原因——nvm 会依据.nvmrc自动切换到仓库锁定的 Node 版本避免因版本不匹配导致的安装或构建异常。搭建本地开发环境分步实战核心思想Web 进程与 Electron 进程分离Bruno 是一款桌面应用其开发模式要求在两个独立终端会话中分别运行两条进程contributing_ua.md终端 1启动 Web/UI 前端开发服务器终端 2启动 Electron 桌面应用由它加载前端产物。完整安装与启动命令# 使用 nodejs 指定版本按仓库 .nvmrc即 v22.12.0 nvm use # 安装依赖--legacy-peer-deps 用于规避部分传递依赖的 peer 冲突 npm i --legacy-peer-deps # 构建 graphql 文档相关包 npm run build:graphql-docs # 构建 bruno query 查询引擎 npm run build:bruno-query # 启动 Web 应用终端 1 npm run dev:web # 启动 Electron 应用终端 2 npm run dev:electron各命令在根 package.json 中均有对应定义dev:web实际执行npm run dev --workspacepackages/bruno-app即运行 packages/bruno-app 工作区内的 rsbuild 开发服务器见 packages/bruno-app/package.jsondev:electron实际执行npm run dev --workspacepackages/bruno-electron对应 packages/bruno-electron/package.json 中的electron .即以 packages/bruno-electron/src/index.js 为入口拉起 Electronbuild:graphql-docs、build:bruno-query分别构建bruno-graphql-docs与bruno-query两个工作区包——这些纯逻辑/文档型子包在应用启动前需要先产出编译结果。值得补充的是仓库还提供了比两步走更省事的一体化入口。根 package.json 中定义了npm run dev执行 scripts/dev.js以及支持热重载的npm run dev:watch执行 scripts/dev-hot-reload.js可用单条命令并发拉起前后端开发进程。预处理子包的另一种选择npm run setup对于想跳过逐个build:*命令、让仓库自动完成依赖安装与子包构建的贡献者根 package.json 提供了聚合脚本npm run setup。查看其实现 scripts/setup.js 可以看到它依次完成了清理各层node_modules→npm i --legacy-peer-deps安装依赖 → 按平台强制安装node-pty平台二进制 → 依次构建 graphql-docs、bruno-query、bruno-common、bruno-converters、bruno-requests、schema-types、bruno-filestore、bruno-sqlite → 打包 bruno-js 沙箱库。这与贡献文档手写命令的最终效果一致可作为自动化替代方案。需要理解的工程细节构建产物依赖顺序仓库采用 monorepo多个工作区包之间存在编译产物级依赖例如usebruno/common、usebruno/schema、usebruno/sqlite等被 packages/bruno-app/package.json 引用。因此首次拉取源码后先执行各build:*脚本、再启动dev:web是必要步骤否则前端进程可能因找不到子包产物而报错。npm run setup正是把这条链路脚本化的产物。常见问题排查Unsupported platform 报错贡献文档专门列出了一条高频故障执行npm install时可能遇到Unsupported platform错误。其成因通常是node_modules中存在为其他平台操作系统/CPU 架构下载的二进制包与当前开发机不匹配。文档给出的标准解法是清理掉所有嵌套的node_modules目录与package-lock.json锁文件后重新安装# 删除所有子目录中的 node_modules find ./ -type d -name node_modules -print0 | while read -d $\0 dir; do rm -rf $dir done # 删除所有 package-lock.json find . -type f -name package-lock.json -delete清理后重新执行npm i --legacy-peer-deps补充说明两点该方案是「兜底」而非首选删除锁文件会丢失依赖版本锁定因此建议仅在常规安装持续失败时使用并且尽量保留一份package-lock.json的备份用于恢复。平台差异的另一来源是node-pty 等原生模块。仓库在 scripts/setup.js 中针对darwin/win32/linux三个平台分别硬编码了对应的lydell/node-pty-*-{arm64,x64}平台包并强制安装这从侧面解释了为何此类工具链对平台极其敏感。日常开发时建议优先使用npm run setup由脚本自行处理平台相关依赖。测试策略npm workspaces 的定向与全量运行Bruno 的测试同样依托 npm workspaces 实现。贡献文档给出了两种运行粒度contributing_ua.md# 只运行 bruno-schema 工作区的测试 npm test --workspacepackages/bruno-schema # 运行所有工作区中定义了 test 脚本的包的测试 npm test --workspaces --if-present这里有两个值得解释的参数语义--workspacepackages/name将命令作用域限定到单一工作区包对应npm test --workspace pkg语法适合在修改某个子包后做快速回归--workspaces会遍历全部工作区执行测试--if-present表示跳过未定义test脚本的包避免因部分纯类型/文档包没有测试脚本而中断整体流程。结合当前仓库可以扩展出更细的测试地图英文版根 contributing.md 与各工作区的 package.json 提供依据除bruno-schema外bruno-query、bruno-common、bruno-converters、bruno-app、bruno-electron、bruno-lang、bruno-toml等工作区也都各自定义了test脚本可逐一替换--workspace参数定向执行。此外仓库还提供更大规模的验证手段根 package.json 中定义了基于 Playwright 的端到端测试脚本test:e2e及test:e2e:ssl、test:e2e:auth、test:e2e:mock-server等按功能域拆分的项目组它们配合 playwright.config.ts 使用适合在功能改动较大、涉及完整 UI 交互链路时运行。提交规范小型 PR 与分支命名贡献文档在协作层面提出了两条硬性要求contributing_ua.mdPR 保持小而聚焦一个 PR 只解决一件事便于 Review、回溯与快速合入遵守分支命名约定feature/功能名仅包含某特定功能的变更例如feature/dark-modebugfix/缺陷名仅包含某特定 bug 的修复例如bugfix/bug-1。围绕这条约定仓库在工程层面也做了配套约束根 package.json 配置了huskynano-staged的 Git 钩子在暂存提交时自动对改动的*.{js,ts,jsx}文件执行npm run lint:fixESLint 配置见 eslint.config.js从而保证进入 PR 的代码已通过基础静态检查。这意味着开发者在本地提交时就能提前暴露格式问题而不是等 CI 阶段再返工。快速自查清单完成阅读后可用以下清单验证自己的开发环境是否就绪nvm use成功切换到 .nvmrc 指定的 Nodev22.12.0npm i --legacy-peer-deps无Unsupported platform报错npm run build:graphql-docs与npm run build:bruno-query或直接npm run setup执行成功终端 1 运行npm run dev:web正常起服务终端 2 运行npm run dev:electron能弹出桌面窗口对单包改动执行npm test --workspacepackages/包名通过按feature/name或bugfix/name命名分支PR 内容保持单一主题。结语从 docs/contributing/contributing_ua.md 这份贡献指南可以看到参与 Bruno 开发的技术门槛集中体现在两点理解「React/rsbuild UI 进程 Electron 主进程」的双进程开发模型以及熟练操作 npm workspaces 下的定向构建与定向测试。只要遵循本文按仓库实际配置校正后的命令序列——以.nvmrc为准锁定 Node 版本、必要时用npm run setup一键完成依赖与子包构建、再分终端启动dev:web与dev:electron——即可顺利跑起本地开发环境。后续请继续以小型化、分支命名规范化的方式提交你的第一个 PR。【免费下载链接】brunoOpensource IDE For Exploring and Testing APIs (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/bruno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考