01 技术栈与环境要求
文档摘要
01 技术栈与环境要求 本节摘要:在动手之前,先把 OpenWork 对运行环境的要求理清楚——它不是「双击一个安装包就完事」的普通桌面应用,而是一个由工作区(pnpm workspace)与任务编排(Turborepo)管理的大型单体仓库,跑起来时桌面外壳、本地服务端、底层引擎会同时启动并彼此通信。本节把这些前提逐项讲清:为什么服务端用 Bun、桌面外壳用 Node + Electron、前端用 React、包管理为什么严格限定、依赖为什么用目录(catalog)锁定版本。把这一节读透,后面遇到任何启动问题你都能自己定位是哪一环出了岔。 一、它是什么形态:多包单体仓库 先建立一个关键认知:OpenWork 在源码层面是一个多包单体仓库(monorepo)。
01 技术栈与环境要求
本节摘要:在动手之前,先把 OpenWork 对运行环境的要求理清楚——它不是「双击一个安装包就完事」的普通桌面应用,而是一个由工作区(pnpm workspace)与任务编排(Turborepo)管理的大型单体仓库,跑起来时桌面外壳、本地服务端、底层引擎会同时启动并彼此通信。本节把这些前提逐项讲清:为什么服务端用 Bun、桌面外壳用 Node + Electron、前端用 React、包管理为什么严格限定、依赖为什么用目录(catalog)锁定版本。把这一节读透,后面遇到任何启动问题你都能自己定位是哪一环出了岔。
一、它是什么形态:多包单体仓库
先建立一个关键认知:OpenWork 在源码层面是一个多包单体仓库(monorepo)。这意味着它不是一个仓库一个包,而是一个仓库里有几十个包(桌面应用、服务端、前端、共享类型库、企业版各组件......),这些包通过工作区机制互相引用、协同构建。
这种结构带来两个直接的环境要求:
- 工作区感知的包管理器:OpenWork 严格限定用 pnpm(不是 npm 或 yarn),因为它的工作区配置依赖 pnpm 的特性。
- 任务编排工具:用 Turborepo 编排几十个包的构建/测试任务,让「改一个包只重建受影响的」成为可能。
💡 为什么必须 pnpm:OpenWork 的工程文档明确禁用 npm 和 yarn。用错包管理器,依赖会装不全或装错,后面一堆「找不到模块」的怪问题。装 pnpm 是第一步,别跳过。
二、运行时:服务端 Bun,桌面 Node
OpenWork 一个有意思的设计是不同组件用不同运行时:
| 组件 | 运行时 | 为什么 |
|---|---|---|
| 服务端(Server) | Bun | 快、原生 TS、单文件打包基础 |
| 桌面外壳(Electron 主进程) | Node | Electron 本身基于 Node |
| 前端(渲染进程) | 浏览器/Electron 渲染 | React 单页应用 |
这意味着你本地要同时有 Bun 和 Node。服务端那部分(整个产品的中枢)跑在 Bun 上,桌面外壳跑在 Node 上,两者通过 HTTP/IPC 通信。
⚠️ 常见坑:只装了 Node 没装 Bun,启动时服务端起不来或报错。两个运行时都要装,版本都要达标。
三、前端:React 19 + 一整套现代工具链
前端是 React 19 单页应用,用了一整套现代工具:
- 构建:Vite
- 状态:TanStack Query、Zustand
- 路由:react-router-dom
- UI 组件:shadcn/ui 风格 + Base UI + Tailwind CSS + Radix
- 编辑器/渲染:CodeMirror、Lexical、Shiki、marked、xterm(终端)
你不需要现在精通这些(第 10 章会讲前端架构),但要知道前端栈比较重,首次装依赖会比较慢——这是正常的,不是卡住了。
四、桌面:Electron + 原生依赖
桌面外壳是 Electron,带了一些原生依赖(需要编译的 Node 模块):
- better-sqlite3:本地数据库
- node-pty:嵌入式终端
- electron-updater:自动更新
原生依赖意味着你的机器上要有编译工具链(Python、C++ 编译器等)。大多数情况下安装脚本会自动处理,但在某些环境(如 Windows 缺 VS Build Tools)会失败。
💡 Windows 用户注意:如果装依赖时报「node-gyp 失败」「找不到编译器」,多半是缺 Visual Studio Build Tools。装一个带 C++ 桌面开发的 Build Tools 通常能解决。
五、依赖锁定:catalog 与补丁
OpenWork 用两种机制管理依赖版本,都值得知道:
1. catalog(目录锁定)
pnpm 的 catalog 功能让你在一个地方声明所有包的依赖版本,各包引用这个目录。好处是版本统一——同一种依赖在所有包里版本一致,避免「A 包用了 React 18、B 包用了 React 19」的版本漂移。
2. patchedDependencies(补丁)
有些第三方依赖有 bug 但等不及上游修,OpenWork 会对它们打补丁。这意味着装依赖时,这些补丁会自动应用。如果你看到 patches 目录里有若干补丁文件,那是正常的——不是你的环境问题。
六、其他隐性依赖
除了上述,还有几个会偶尔回来的依赖:
- Docker:跑企业版(Den)的本地开发需要 Docker(起 MySQL 等)。
- Git:工作区管理、版本控制。
- 一个兼容 Agent 或模型凭据:OpenWork 是平台,它需要一个 Agent 或模型来真正干活。
七、环境自检清单
动手前,对照这张表逐项确认:
| 检查项 | 命令(概念性) | 期望 |
|---|---|---|
| pnpm 已安装 | pnpm --version |
正常返回 |
| Node 已安装 | node --version |
版本达标 |
| Bun 已安装 | bun --version |
版本达标 |
| Docker(跑 Den 用) | docker --version |
正常返回 |
| Git 可用 | git --version |
正常返回 |
| 编译工具链(原生依赖) | — | Windows 装 VS Build Tools |
| Agent 或模型凭据 | — | 至少一个可用 |
本节要点回顾
- OpenWork 是多包单体仓库,严格限定 pnpm(禁 npm/yarn),用 Turborepo 编排任务。
- 不同组件不同运行时:服务端 Bun、桌面 Node、前端浏览器/渲染进程——两个运行时都要装。
- 前端栈较重(React 19 + Vite + 一堆库),首次装依赖慢是正常的。
- 桌面有原生依赖(sqlite3/node-pty/更新器),需要编译工具链,Windows 注意 VS Build Tools。
- catalog 统一版本、patches 打第三方补丁,看到 patches 目录是正常的。
- 自检清单:pnpm/Node/Bun/Docker/Git/工具链/Agent——逐项确认能省后面大部分麻烦。
环境清楚了,下一步就是把它装上、双形态启动起来——这正是下一节的主题。