Bruno 开源 API 客户端的本地开发环境搭建与开源贡献指南基于德语贡献文档【免费下载链接】brunoOpensource IDE For Exploring and Testing APIs (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/brunoBruno 是一款开源的 API 探索与测试 IDEPostman / Insomnia 的轻量级替代品其官方仓库以 npm workspaces 组织的 monorepo 形式维护全部代码。本文以仓库中的德语贡献指南 docs/contributing/contributing_de.md 为核心骨架完整覆盖技术栈、Node 环境要求、依赖安装、React 前端与 Electron 桌面端的双进程开发启动流程、常见错误排查、测试命令与 Pull Request 提交流程并结合当前仓库源码逐项佐证。读完本文你将能够在一台干净的机器上把 Bruno 跑起来、修改代码并规范地向社区提交贡献。说明文中所有文件路径均以仓库根目录为起点便于直接查阅对应源码。Bruno 项目是什么Bruno 是一款面向 API 开发者的开源桌面应用仓库自述为 Opensource IDE For Exploring and Testing APIs轻量级 Postman / Insomnia 替代方案。与绝大多数在线同步的 API 工具不同Bruno 强调数据留在本地它以桌面应用形态运行直接在文件系统上读写请求集合从而天然支持 Git 版本管理。开发者不必再依赖云账号也可以让整个集合文件夹直接进入 Git 仓库。仓库采用 monorepo 结构核心两大运行载体分别是React 渲染层负责 UI 与交互与Electron 主进程/外壳负责桌面窗口与本地文件能力。德语贡献文档中提到的技术栈细节是理解整套工程的起点。Bruno 的技术栈与关键依赖德语版贡献指南明确给出了当前工程依赖的核心技术桌面外壳Electron让本地集合成为可能前端渲染React配合构建与开发服务器工具链CSSTailwind代码编辑器CodeMirror状态管理Redux图标Tabler Icons表单FormikSchema 校验Yup请求客户端axios文件系统监听chokidar以上描述都能在当前仓库源码中得到验证例如 packages/bruno-app/package.json 的 dependencies 中可看到reduxjs/toolkit、codemirror、formik、tabler/icons、yup、i18next、react19 等依赖packages/bruno-electron/package.json 中则包含electron ~37.6.1、axios 1.18.0、chokidar、express、simple-git等桌面端与本地集合管理所需依赖。需要留意的一个版本差异德语文档与简体中文版 docs/contributing/contributing_cn.md 都提到 Web 层基于 Next.js 构建但对照当前仓库实际脚本packages/bruno-app/package.json 中dev为rsbuild dev当前前端渲染层已改用React rsbuild仓库根目录 contributing.md 的英文版也注明 We use React for the frontend and rsbuild for build and dev server。这说明各语言翻译版贡献文档撰写时代略有差异实际开发请以仓库内脚本与英文主文档为准。Monorepo 与 npm workspaces 布局德语文档强调项目使用npm workspaces多工作区。仓库根目录 package.json 中声明了 16 个工作区包构建与测试大量依赖 workspace 机制在包之间调度。其中与跑起来直接相关的有工作区目录包职责从目录结构与 package.json 归纳packages/bruno-appReact 渲染层应用UI、编辑器、各面板开发/构建均基于 rsbuildpackages/bruno-electronElectron 桌面外壳主进程、IPC、本地集合、代理、模拟服务等packages/bruno-cli命令行版 Brunobru支持无界面运行集合packages/bruno-common前后端共享的公共逻辑运行时、schema 校验、codegen 等packages/bruno-schema集合/环境/请求等对象的 Yup 数据模型定义packages/bruno-schema-types与 schema 对应的 TypeScript 类型packages/bruno-query集合查询索引逻辑packages/bruno-js脚本沙箱req/res 对象、测试断言等执行环境packages/bruno-lang.bru语言解析器packages/bruno-convertersPostman / Insomnia / OpenAPI / WSDL 等格式转换器packages/bruno-graphql-docsGraphQL 文档浏览器packages/bruno-requests请求发送、鉴权、WebSocket 等请求层实现packages/bruno-filestore集合在文件系统中的存储、索引格式packages/bruno-sqliteWeb/Node 侧的 SQLite 数据层packages/bruno-tomlTOML 解析工具packages/bruno-tests各类集成测试用例与脚本库这种布局意味着开发时通常需要先在bruno-app等包内完成代码修改再将编译产物提供给 Electron 主进程加载。环境要求Node 与 npm德语文档列出的硬性前提是Node v22.x 或最新 LTS以及 npm 8.x。仓库在根目录维护了 .nvmrc 文件当前内容为v22.12.0因此使用 nvm 管理 Node 版本时只需在仓库根目录执行nvm use该命令会读取.nvmrc并自动切换到你需要的 Node v22 环境避免因版本过新/过旧导致的构建或运行时兼容问题。安装依赖为什么要用--legacy-peer-deps德语文档给出的第一步是安装依赖npm i --legacy-peer-deps--legacy-peer-deps的作用是忽略 npm 的 peerDependencies 自动解析规则改用旧版 npm 的宽松处理绕过某些第三方库 peer 依赖版本冲突导致的安装失败。这一点与仓库根 package.json 中大量overrides字段例如将axios强制覆盖为1.18.0、tar为7.5.22等相互印证——Bruno 依赖链很长出于安全与兼容考虑做了大量版本锁定开发者日常安装请务必保留--legacy-peer-deps参数。构建依赖包子产物Bruno 的多个 workspace 包之间通过编译产物互相引用。直接运行桌面端前需要先把相关包构建出来。德语文档给出的最小构建步骤是# 构建 graphql 文档组件 npm run build:graphql-docs # 构建 bruno 查询索引包 npm run build:bruno-query对照英文版 contributing.md 与 scripts/setup.js完整的依赖包构建清单还包括npm run build:bruno-common npm run build:bruno-converters npm run build:bruno-requests npm run build:schema-types npm run build:bruno-filestore npm run build:bruno-sqlite # 打包 JS 沙箱运行库 npm run sandbox:bundle-libraries --workspacepackages/bruno-js这些构建脚本的映射都定义在根 package.json 的scripts区如build:bruno-query: npm run build --workspacepackages/bruno-query。如果你希望一条命令完成全部工作仓库还提供了自动化脚本npm run setup它由 scripts/setup.js 实现会依次执行清理各子目录node_modules→npm i --legacy-peer-deps安装依赖 → 按操作系统强制安装平台相关二进制依赖scripts/setup.js 中根据darwin/win32/linux分别安装对应架构的lydell/node-pty-*→ 依次构建上述所有前置包 → 打包 bruno-js 沙箱库。启动本地开发环境双进程架构德语文档明确指出Bruno 以桌面应用形态开发需要在两个终端分别启动 React 层与 Electron 层。先确认 node 版本并装好依赖上文已述然后构建前置产物最后分别运行# 终端 1启动 Reactrsbuild开发服务器 npm run dev:web # 终端 2启动 Electron 桌面壳 npm run dev:electron从根 package.json 的脚本定义可以看出dev:web实际是npm run dev --workspacepackages/bruno-app而packages/bruno-app的dev脚本为rsbuild dev即启动 rsbuild 开发服务器托管 UIdev:electron则进入packages/bruno-electron执行electron .主入口为 packages/bruno-electron/src/index.js。如果不想手动开两个终端仓库还提供了一条并发启动命令npm run dev该命令由 scripts/dev.js 实现它会以子进程方式启动 rsbuild 开发服务器并通过正则Local:\shttp://localhost:(\d)从 rsbuild 输出中自动探测实际端口然后把端口号通过BRUNO_DEV_PORT环境变量传给 Electron 子进程见 scripts/dev.js。也就是说即使 3000 端口被占用导致 rsbuild 自动换端口Electron 也能正确连上 Web 开发服务器。此外仓库还提供了带热更新的dev:watchnpm run dev:watch见根 package.json实现位于 scripts/dev-hot-reload.js适合需要跨包联动热重载的场景。自定义 Electron 的 userData 目录开发调试技巧英文版 contributing.md 补充了一个非常实用的开发期技巧同样得到源码支持在 packages/bruno-electron/src/index.js 中当处于开发模式且设置了ELECTRON_USER_DATA_PATH环境变量时应用会调用app.setPath(userData, ...)重定向 Electron 的用户数据目录。利用这一点你可以让一次本地开发会话使用一个全新的、可随意清理的沙盒数据目录避免污染日常使用的配置ELECTRON_USER_DATA_PATH$(realpath ~/Desktop/bruno-test) npm run dev:electron运行后桌面会生成bruno-test目录并作为本次会话的userData使用。Bruno 的许多本地状态例如 packages/bruno-electron/src/ipc/sqlite.js 中的bruno.db、packages/bruno-electron/src/services/mount/file-index.js 中的挂载快照索引都存放在userData下通过该技巧可以隔离开发数据也方便排查与干净状态相关的 bug。TroubleshootingUnsupported platform 错误德语文档专门提醒了一个高频坑执行npm install时可能遇到Unsupported platform错误。这类错误通常与平台相关的可选依赖optional dependency如上面提到的lydell/node-pty-*或 peer 依赖解析冲突有关。官方给出的修复方式是从子目录中彻底删除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如果仍然遇到平台相关依赖问题可以运行仓库内置的npm run setup其内部会按你的操作系统强制安装对应架构的二进制依赖参见 scripts/setup.js 中forceInstallPlatformDeps实现。如何运行测试德语文档给出了两个层级的测试命令先针对单个工作区再全量运行所有工作区测试。针对bruno-schema集合/环境/请求模型包npm test --workspacepackages/bruno-schema该包的测试位于源码目录内的*.spec.js文件中例如 packages/bruno-schema/src/collections/requestSchema.spec.js、packages/bruno-schema/src/collections/environmentSchema.spec.js 等它们验证 Yup schema 对.bru集合对象的约束行为是理解集合/环境/请求模型底层定义最直接的入口。对仓库内所有声明了 test 脚本的工作区执行测试npm test --workspaces --if-present--if-present会跳过那些没有定义test脚本的工作区例如 bruno-schema 的 package.json 中test: jest才会被调用避免全量运行时因缺失脚本而报错。如果只想针对某一个包迭代可以参照根 package.json 及英文版 contributing.md 中的方式逐个运行例如bruno-app、bruno-electron、bruno-lang、bruno-toml等均有独立的 jest 测试入口。仓库还维护了一套基于 Playwright 的端到端测试脚本位于根 package.json 的test:e2e等配置见 playwright.config.ts 与tests/目录下大量.spec.ts适合在完成 UI 改动后做回归验证不过它属于进阶内容第一次贡献时可以先用上文的工作区单元测试验证核心逻辑。提交 Pull Request 的约定德语文档对协作规范做了三点明确要求这也是评审者最在意的提交卫生保持 PR 小而聚焦一个 PR 只做一件事便于 review、降低合入风险分支命名遵循格式feature/[feature name]只包含某个新功能的改动。例如feature/dark-modebugfix/[bug name]只包含针对某个 bug 的修复。例如bugfix/bug-1。这些约定与仓库配套的工程化约束是一致的根 package.json 中配置了 husky nano-staged会在提交前对暂存的*.{js,ts,jsx}文件自动执行npm run lint:fix仓库根目录还维护了 eslint.config.js 与 CODING_STANDARDS.md编码规范建议在提交前阅读并保持代码风格一致。更多参考资源主语言贡献指南内容最完整、最新contributing.md简体中文翻译版docs/contributing/contributing_cn.md与德语版同属官方维护的翻译集见 contributing.md 顶部的语言切换列表发布相关文档见 docs/publishing/对应根目录 publishing.md项目主文档readme.md最后再提醒一句德语文档中技术栈为 Next.js的表述属于翻译版写作时的旧信息动手开发前请以根目录英文 contributing.md、各 package.json 中的实际脚本和.nvmrc中锁定的 Node v22.12.0 为准。依照本文的流程你就可以在本地完成 Bruno 的搭建、修改与提交参与到让 Bruno 变得更好的共建中来。【免费下载链接】brunoOpensource IDE For Exploring and Testing APIs (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/bruno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考