如何从源码构建Nimbalyst：Electron+Lexical的pnpm monorepo开发环境搭建-开发者社区

【免费下载链接】nimbalyst

Nimbalyst - The open-source visual workspace for Claude Code, Codex, and OpenCode. Run multiple coding agents in parallel, edit their work visually in markdown, mockups, and diagrams, and track tasks. Free, MIT-licensed desktop app for macOS, Windows, Linux, with mobile companion for iOS and Android.

项目地址：https://gitcode.com/gh_mirrors/ni/nimbalyst

点击查看免费下载

Nimbalyst 是一款基于 Electron + Lexical 的开源可视化编程工作区，支持并行运行 Claude Code、Codex、OpenCode 等多个 AI 编码代理，并可用 Markdown、Mockup、图表可视化地审阅它们的改动。想动手改它、或只是好奇它如何跑起来？这篇完整指南带你从零完成 Nimbalyst 源码构建：一个由 pnpm monorepo 管理的 20+ 子包工作区，全程只需 Node 24、pnpm 12 和三条命令。

🗺️ 先看清全貌：pnpm monorepo 项目结构

Nimbalyst 的仓库是一个标准的 pnpm monorepo。打开根目录的 pnpm-workspace.yaml，可以看到所有参与协作的子包：

子包	作用
`packages/electron`	桌面端主应用（Electron 主进程、渲染进程）
`packages/runtime`	共享运行时逻辑，被 Electron 与 CLI 复用
`packages/tracker-core`/`tracker-schema`/`tracker-engine`	任务追踪（Tracker）三件套
`packages/collab-protocol`/`collab-client`	实时协作协议与客户端
`packages/extension-sdk`	扩展开发套件
`packages/extensions/*`	内置扩展：Excalidraw、CSV 表格、Git、Mockup 等
`packages/ios`/`packages/android`	移动端伴侣应用

编辑器内核是 Meta 的 Lexical 框架，根 package.json 中锁定lexical@^0.44.0及其十几个插件包，并在 pnpm-workspace.yaml 中用patches/目录对@lexical/table、@lexical/yjs打了小补丁。

🧰 环境准备：Node 24 + pnpm 12（核心关键词：pnpm monorepo 开发环境）

版本要求由 .nvmrc 和 package.json 的engines字段共同约束：

Node ≥ 24（仓库自带.nvmrc，值为 24）
pnpm ≥ 12，packageManager字段锁定为pnpm@12.9.1

Node 24 自带 corepack，所以准备工作只有两步：

git clone https://gitcode.com/gh_mirrors/ni/nimbalyst cd nimbalyst corepack enable

⚠️ 小提醒：仓库根目录的devEngines配置会直接拒绝 npm——在根目录敲任何npm命令都会报EBADDEVENGINES。请一律使用 pnpm 等价命令，这是 CONTRIBUTING.md 明确说明的。

📦 一键安装依赖：pnpm install 背后发生了什么

在仓库根目录执行：

pnpm install

这一条命令会串行完成四件事，理解它们能帮你少走弯路：

扁平化安装：pnpm-workspace.yaml 设置nodeLinker: hoisted，生成类似 npm 的扁平node_modules，因为 electron-builder 的打包链路依赖这种结构。
运行prepare钩子：见 package.json，它会清理过期的 npm 锁文件、安装 git hooks，并预构建tracker-core、tracker-schema、tracker-engine、local-wiki四个包。
校验原生模块白名单：allowBuilds字段是安装脚本的安全门——只有白名单内的依赖（electron、esbuild、better-sqlite3、sharp等）才被允许执行构建脚本，其余依赖若有 postinstall 会让安装直接失败。
修复 Electron 二进制：packages/electron的postinstall会执行install-electron并重建原生依赖；若此前用--ignore-scripts跳过过，可手动跑 setup-dev.sh 补救。

另有一个有趣的机制：minimumReleaseAge: 4320让 pnpm 拒绝解析发布不满 72 小时的新版本，避免不稳定的依赖进入你的构建。

🚀 启动开发模式：pnpm run dev 三兄弟

所有开发命令都在 packages/electron 目录下执行，三种姿势对应不同场景（详见 docs/DEVELOPING_NIMBALYST.md）：

命令	适用场景
`pnpm run dev`	常规渲染进程开发，热更新（HMR）够用
`pnpm run dev:loop`	要频繁重启应用时，推荐 ⭐
`pnpm run dev:user2:loop`	启动第二个隔离实例，独立 userData 与`out2/`输出，避免双实例互相干扰

cd packages/electron pnpm run dev

dev.sh 脚本在拉起electron-vite dev前，会先增量构建 extension-sdk（约 1 秒），防止渲染进程读到过期的扩展 SDK 产物。

主进程、preload 或启动流程的改动需要重启应用才能生效。此时dev:loop价值凸显：它运行 dev-loop.sh，在应用内输入/restart或点击重启按钮后，脚本读取信号文件并自动拉起新实例，形成「改代码 → 重启 → 复测」的可靠循环——而且进行中的 AI 代理会话会在重启后排队继续。

启动后建议进入全局设置 → Advanced，开启Extension Dev Tools。这样 AI 代理就能直接对运行中的应用做只读数据库查询、读主进程日志、在渲染进程执行 JS 检查 DOM，调试效率倍增。

🔨 构建可分发的安装包

验证功能正常后，可以用 electron-builder 打出正式安装包（完整机制见 docs/ELECTRON_PACKAGING.md）：

cd packages/electron pnpm run build:unpack # 先解包验证，速度最快 pnpm run build:mac # 或 build:win / build:linux

build脚本会依次生成主进程/预加载 bundle、worker bundle 和 Cloudflare 沙箱产物，再交给 electron-builder 按asarUnpack规则把原生模块与各家 Agent SDK 放到app.asar.unpacked正确位置——这套布局保证打包后的应用与开发态行为一致。

✅ 测试与类型检查

提交前建议跑一遍官方验证组合：

pnpm typecheck && pnpm test:prepush

端到端测试基于 Playwright（pnpm run test:e2e）。两个关键点：E2E 必须串行执行；PGLite 数据库需按 Electron 实例隔离（通过NIMBALYST_USER_DATA_PATH指定独立目录）。更多细节见 docs/E2E_TESTING.md。

❓ 常见问题排查（FAQ）

npm 命令全部报错？正常现象，根目录禁用了 npm，改用 pnpm。
pnpm install卡在某个依赖的构建脚本上？检查 pnpm-workspace.yaml 的allowBuilds：未列入的依赖一律不执行安装脚本，这是有意的安全策略。
Electron 窗口起不来？多半是 Electron 二进制缺失，在packages/electron下运行pnpm exec install-electron即可修复。
开发态数据库被外部工具锁住？切勿在 Nimbalyst 运行时用 Node/CLI 直接打开 PGLite 文件，请使用应用内提供的数据库工具。