如何快速打包Cabinet桌面应用Electron Forge构建macOS/Windows安装包完整指南【免费下载链接】cabinetAI-first knowledge base and startup OS项目地址: https://gitcode.com/gh_mirrors/cabinet3/cabinetCabinet 是一个 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 与 npmmacOS 打包需在 macOS 上执行Windows 安装包建议在本机 Windows 或 CI 上构建应用图标放在 electron/assets/包含.icnsmacOS与.png先克隆代码并安装依赖git clone https://gitcode.com/gh_mirrors/cabinet3/cabinet cd cabinet npm install二、三条命令走完全流程打开 package.json 可以看到打包脚本已编排好三步流水线脚本作用electron:make构建 预打包 制作 macOS 安装包electron:make:win同上但指定--platform win32交叉构建 Windowselectron:package只打包可执行文件不制作安装介质实际只需运行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️⃣ 制作器makersMakerDMG生成 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为桌面端做三件关键事用 esbuild 打包守护进程把 server/cabinet-daemon.ts 打成单文件cabinet-daemon.cjs桌面应用启动时由内置 Node 直接运行无需用户装 Node预置 node-pty 原生模块把node-pty的预编译二进制放入.native/目录macOS 上运行时会复制到用户数据目录以通过 Gatekeeper 检查拷贝种子内容从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 提示。官方建议不要自签证书来绕过正式发布前建议接入云端签名服务。七、验证打包产物像用户一样冒烟测试打包成功 ≠ 可用。项目内置了两套官方冒烟测试模拟用户真实安装体验macOSnpm run test:electron:macos由 scripts/test-electron-macos-package.mjs 挂载 DMG、启动Cabinet.app验证/api/health与/api/health/daemon两个健康检查接口Windowsnpm run test:electron:windows由 scripts/test-electron-windows-package.ps1 运行生成的Setup.exe、启动安装后的Cabinet.exe并做同样的健康检查最后卸载测试副本本地只需一条命令npm run test:electron:macos测试通过意味着 Web 服务与守护进程都在桌面应用内正常工作。八、常见问题速查现象原因与解决Windows 打包报 Description is requiredSquirrel 需要 nuspec 描述检查 forge.config.cjs 中MakerSquirrel的description字段macOS 公证 403 错误Apple 开发者协议未同意/过期登录后接受再重新构建打包卡在复制文件、报 ENOENTNext.js 追踪产生的悬空符号链接升级后由removeDanglingTracedSymlinks()自动清理桌面端数据放哪里macOS 默认在~/Library/Application Support/Cabinet/cabinet-data与安装目录分离更新不覆盖数据更多细节可参考官方文档 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考