如何从源码构建 Open Cowork：开发环境搭建、本地调试与打包发行完整指南-迪斯科星球

如何从源码构建 Open Cowork：开发环境搭建、本地调试与打包发行完整指南

【免费下载链接】open-coworkOpen-source AI agent desktop app for Windows & macOS. One-click install Claude Code, MCP tools, and Skills — with sandbox isolation, multi-model support, and Feishu/Slack integration.项目地址: https://gitcode.com/gh_mirrors/op/open-cowork

Open Cowork是一款开源的 AI Agent 桌面应用（支持 Windows 与 macOS），基于 Electron + React + TypeScript 构建，可一键安装 Claude Code、MCP 工具与 Skills，并内置沙箱隔离、多模型支持与飞书/Slack 集成。本文将从源码构建 Open Cowork 出发，带你完成开发环境搭建、本地调试与打包发行三大环节，是面向新手的一份完整指南 🚀

一、构建前的环境准备：Node.js 与 npm 版本要求

在开始源码构建之前，请先确认本地环境满足以下要求：

依赖	版本要求	说明
Node.js	≥ 22	项目`engines`字段要求，与 CI 保持一致
npm	10+	随 Node.js 自带，无需单独安装
操作系统	macOS / Windows	开发调试的官方支持平台

💡 小贴士：项目通过 scripts/download-node.js 会自动下载一份v22.22.0 的独立 Node 二进制（用于随安装包分发，而非构建本身），请预留足够的磁盘空间与网络带宽。

二、克隆仓库并安装依赖：一键完成

1. 克隆代码

git clone https://gitcode.com/gh_mirrors/op/open-cowork cd open-cowork

2. 安装依赖

npm install

这条命令看似普通，实际会触发 package.json 中的postinstall钩子，一次性完成三件事：

应用补丁（patch-package，修复依赖库问题）
下载平台对应的 Node 二进制到resources/node/
针对 Electron 运行时重编译 better-sqlite3 原生模块

也就是说，一条npm install就把源码构建最容易踩坑的原生模块问题都处理好了 ✅

三、启动开发环境：npm run dev 本地调试

1. 常用命令速查

命令	作用
`npm run dev`	启动 Vite + Electron 开发服务器
`npm run dev:with-python`	额外准备内置 Python 运行时后启动
`npm run lint`	ESLint 代码检查
`npm run test`	启动 Vitest 测试（watch 模式）
`npx tsc --noEmit`	类型检查（不产出文件）
`npm run build`	完整生产构建 + 打包安装包

执行npm run dev后，开发流程会自动串联：下载 Node 二进制 → 编译 WSL2/Lima 沙箱 agent → 用 esbuild 打包 MCP 服务器 → 启动 Vite 热更新 + Electron 窗口。修改src/renderer/下的 React 代码会即时热更新；修改src/preload/则会自动刷新页面，无需手动重启 ⚡

2. 项目结构：先认识再调试

src/main/— Electron 主进程：agent 执行、MCP、沙箱、会话、记忆、远程通道（飞书/Slack）等
src/preload/— 预加载脚本，桥接主进程与渲染进程
src/renderer/— React 前端界面（组件、hooks、i18n、Zustand 状态管理）
src/tests/与tests/— 与源码镜像路径组织的测试文件
electron-builder.yml — 打包发行配置
CONTRIBUTING.md — 完整的贡献者指南

3. 调试与测试技巧

运行单测：npx vitest run单次执行（CI 同款），npm run test:coverage可生成覆盖率报告
日志排查：应用内自带日志查看器，也可打开 Electron DevTools 控制台
代码风格：提交前运行npm run lint与npm run format，项目遵循 TypeScript strict 模式、Tailwind CSS 与 Conventional Commits 规范（由 husky + commitlint 强制）

四、打包发行：electron-builder 构建安装包

当开发调试完成，想要产出可分发的安装包时：

npm run build

该命令按以下顺序执行完整流水线：下载 Node 二进制 → 准备 GUI 工具与 Python 运行时 → 编译沙箱 agent → 打包 MCP 服务器 →tsc+vite build构建应用 → 预构建检查 →electron-builder 产出安装包📦

针对 Windows 平台，项目提供了专门的 scripts/build-windows.js（即npm run build:win），自动处理 Electron 缓存校验与构建目录隔离，可显著减少 Windows 下的构建失败。

打包产物说明

输出目录为release/，产物命名格式：Open Cowork-{version}-{平台}-{架构}.{ext}
Windows：NSIS 安装程序（x64），支持自选安装目录
macOS：arm64 应用包（含 DMG 压缩钩子，见 scripts/compress-dmg.js）
Linux：AppImage（x64）

打包过程中的两个关键机制值得了解：

afterPack 瘦身钩子：scripts/after-pack.js 会移除与目标平台不符的原生二进制及冗余语言包，通常可节省约160MB体积
extraResources 资源打包：MCP 服务器、独立 Node 运行时、Python 环境与内置 Skills 都通过 electron-builder.yml 中声明的extraResources随包分发，保证最终用户"开箱即用"

构建产物速查清单

检查项	确认方式
产物生成	`release/`目录出现安装程序文件
应用可启动	安装后打开应用，界面正常渲染
模型可配置	进入设置页完成 API 密钥配置
MCP/Skills 可用	应用内对应面板显示已加载

五、常见问题速答

Q：npm install卡在下载 Node 二进制？脚本支持断点重试，建议检查网络后重新执行npm run download:node单独补齐。

Q：better-sqlite3 报原生模块错误？说明重编译未针对 Electron 运行时执行，手动运行npm run rebuild即可。

Q：想清理重新构建？运行npm run clean可删除dist、dist-electron、release等全部构建产物。

Q：macOS 上想快速尝鲜 CI 构建版本？可使用npm run deploy:local（见 scripts/deploy-local.sh），它会自动拉取当前分支的 CI 产物并安装到本机。

写在最后

到这里，你已经掌握了从源码构建 Open Cowork 的完整路径：Node 22 环境 → npm install → npm run dev 调试 → npm run build 发行。整个构建体系通过 npm scripts 将复杂的 Electron + 原生模块 + 多运行时打包流程封装成三条简单命令，大大降低了参与贡献的门槛。如果想进一步深入，建议继续阅读 CONTRIBUTING.md 了解分支策略与 PR 规范，动手提交你的第一个 PR 吧！💪

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析