企业官网建设流程全解析

如何快速打包Cabinet桌面应用：Electron Forge构建macOS/Windows安装包完整指南

【免费下载链接】cabinetAI-first knowledge base and startup OS项目地址: https://gitcode.com/gh_mirrors/cabinet3/cabinet

Cabinet 是一个 AI 优先的自托管知识库与创业操作系统，全部数据以 Markdown 文件形式保存在你的电脑上。本文带你用 Electron Forge 完成 Cabinet 桌面版打包：一条命令构建 Next.js 生产版本、预打包运行时，再分别产出 macOS 的 DMG/ZIP 与 Windows 的 Squirrel 安装包，并覆盖签名、公证与冒烟测试全流程。

一、打包前准备：环境要求

Cabinet 的桌面端基于 Electron 36 + Next.js 16 构建，入口是 electron/main.cjs，打包配置集中在 forge.config.cjs。

环境清单

• Node.js 20+ 与 npm
• macOS 打包需在 macOS 上执行；Windows 安装包建议在本机 Windows 或 CI 上构建
• 应用图标放在 electron/assets/，包含.icns（macOS）与.png

先克隆代码并安装依赖：

git clone https://gitcode.com/gh_mirrors/cabinet3/cabinet cd cabinet npm install

二、三条命令走完全流程

打开 package.json 可以看到打包脚本已编排好三步流水线：

实际只需运行：

npm run electron:make # macOS：产出 .dmg 与 .zip npm run electron:make:win # Windows：产出 Squirrel Setup.exe 与 zip

产物统一输出到out/目录，安装介质在out/make/下，可直接分发或上传发布。

三、看懂 forge.config.cjs：打包核心配置

forge.config.cjs 是整个打包流程的"大脑"，新手重点看四处即可：

1️⃣ 文件裁剪（PACKAGER_IGNORE）打包时排除.git、src、server、test等开发目录，只保留运行必需文件，大幅减小安装包体积；asar.unpackDir将.next/standalone解包出来，让内置 Node 服务可执行。

2️⃣ 制作器（makers）

• MakerDMG：生成 macOS 安装光盘镜像，使用ULFO布局格式
• MakerSquirrel：生成 Windows 安装程序，内置自动更新通道
• MakerZIP：两个平台各出一份免安装压缩包

3️⃣ 签名与公证（osxSign / osxNotarize）只有设置了APPLE_ID等环境变量时才启用，未设置则走 Ad-hoc 本地签名，方便开发自测。

4️⃣ Windows 描述必填项MakerSquirrel中显式声明了description——这是electron-winstaller的硬性要求，缺失会导致打包直接报错 "Description is required"。

四、electron:prep 预打包脚本在做什么

electron:make中间的electron:prep步骤执行 scripts/prepare-electron-package.mjs，为桌面端做三件关键事：

1. 用 esbuild 打包守护进程：把 server/cabinet-daemon.ts 打成单文件cabinet-daemon.cjs，桌面应用启动时由内置 Node 直接运行，无需用户装 Node；
2. 预置 node-pty 原生模块：把node-pty的预编译二进制放入.native/目录，macOS 上运行时会复制到用户数据目录以通过 Gatekeeper 检查；
3. 拷贝种子内容：从resources/目录放入默认页面与智能体模板，保证首次启动开箱即用。

五、macOS 签名与公证配置

发布给真实用户的 macOS 应用需要 Developer ID 签名 + 公证。forge.config.cjs 中通过 5 个环境变量控制：

• APPLE_ID/APPLE_APP_PASSWORD/APPLE_TEAM_ID：公证用
• APPLE_SIGN_IDENTITY：签名身份
• 签名权限声明在 electron/entitlements.mac.plist，其中apple-events权限用于 Apple Notes 导入功能

注意：如果打包时公证报 403 "a required agreement is missing"，不是代码问题，而是 Apple 开发者账号有待同意的协议，登录开发者网站接受后即可。

六、Windows 签名（可选但推荐）

forge.config.cjs 支持通过环境变量启用 Authenticode 签名：

• WINDOWS_CERTIFICATE_FILE：.pfx证书路径
• WINDOWS_CERTIFICATE_PASSWORD：证书密码

未配置证书时打包不会失败，只是用户安装时可能看到"未知发布者"或 SmartScreen 提示。官方建议不要自签证书来绕过，正式发布前建议接入云端签名服务。

七、验证打包产物：像用户一样冒烟测试

打包成功 ≠ 可用。项目内置了两套官方冒烟测试，模拟用户真实安装体验：

• macOS：npm run test:electron:macos，由 scripts/test-electron-macos-package.mjs 挂载 DMG、启动Cabinet.app，验证/api/health与/api/health/daemon两个健康检查接口
• Windows：npm run test:electron:windows，由 scripts/test-electron-windows-package.ps1 运行生成的Setup.exe、启动安装后的Cabinet.exe并做同样的健康检查，最后卸载测试副本

本地只需一条命令：

npm run test:electron:macos

测试通过意味着 Web 服务与守护进程都在桌面应用内正常工作。

八、常见问题速查

更多细节可参考官方文档 docs/deployment-packaging-versioning.md 与桌面端自动更新说明：macOS 使用update-electron-app每 4 小时自动检查新版本，下载完成后提示重启即可，用户数据因位于应用包之外而完全不受影响。

总结

Cabinet 的桌面打包流程可以浓缩为：装依赖 →npm run electron:make→ 跑冒烟测试。Electron Forge 负责把 Next.js 生产构建、内置 Node 运行时与原生模块组装成开箱即用的 DMG 和 Setup.exe，签名公证交给环境变量按需开启。按本文步骤操作，你在半小时之内就能得到一套可分发的 macOS 与 Windows 安装包。

【免费下载链接】cabinetAI-first knowledge base and startup OS项目地址: https://gitcode.com/gh_mirrors/cabinet3/cabinet