从Web到桌面：CC-Viewer Electron打包、macOS代码签名与公证的完整实践-开发者社区

【免费下载链接】cc-viewer

A request monitoring system for Claude Code that captures and visualizes all API requests and responses in real time. Helps developers monitor their Context for reviewing and debugging during Vibe Coding.

项目地址：https://gitcode.com/gh_mirrors/cc/cc-viewer

点击查看免费下载

CC-Viewer（cc-viewer）是一款面向 Claude Code 的请求监控系统，能实时捕获并可视化所有 API 请求与响应，帮助开发者在 Vibe Coding 过程中审查与调试上下文。它原生形态是 Web 应用，而本文带你走通CC-Viewer Electron 打包全流程：如何把 Web 应用装进桌面壳、如何用 electron-builder 产出安装包，以及macOS 代码签名与公证（Notarization）的最快配置方法。

桌面版架构：Web 应用如何装进 Electron

CC-Viewer 桌面端采用「npm 包载荷 + Electron 外壳」的组合架构，核心思路只有一条：

载荷（payload）：packages/app即发布到 npm 的完整应用（server、前端 dist、CLI、拦截器等）；
外壳（shell）：apps/electron/electron/ 下的 main.js 负责窗口与进程管理。

外壳采用多标签架构：BaseWindow顶部是标签栏，每个标签是一个独立的WebContentsView，各自fork('tab-worker.js')启动一套隔离的代理 + 服务 + PTY。主进程通过探测../server/server.js是否存在来区分「打包布局」与「开发布局」，这让同一份外壳代码在仓库内开发和打包产物里都能正确工作。

一键打包：assemble-app.mjs 如何拼装 stage 目录

在pnpm run electron:build背后，assemble-app.mjs 会先执行 Web 端构建，再从零重建apps/electron/stage暂存目录，共 5 步：

触发packages/app的 assemble 脚本，把 Web 前端产物复制到位；
校验server、cli.js、dist等 8 个载荷输入齐全，缺任何一个都会立即报错而不是打出残缺包；
清空并重建stage，把载荷与electron/外壳并排放入；
由 stage-manifest.mjs 生成stage/package.json——版本号取自 npm 包，main指向electron/main.js，运行时依赖完整继承自@ccv/electron，并显式拒绝workspace:协议出现在打包产物中；
把@ccv/core以真实文件形式 vendor 进stage/node_modules（因为0.0.0版本永远无法从注册表解析）。

这一步保证了桌面包与 npm 包版本严格一致，也保证了electron/与server/的相对位置不变——这正是外壳 rootDir 探测所依赖的布局契约。

electron-builder.yml：关键配置一眼看懂

electron-builder.yml 是打包配置的核心，几个值得注意的点：

配置项	值	作用
`directories.app`	`stage`	打包源是拼装后的暂存目录
`directories.output`	`electron-dist`	产物输出到`apps/electron/electron-dist/`
`asar`	`false`	不压缩为 asar，方便直接定位原生模块
`npmRebuild`	`true`	自动对`node-pty`等原生模块做平台重建
`mac.target`	`dmg`+`zip`	同时产出安装盘与签名用 zip
`hardenedRuntime`	`true`	启用强化运行时（公证的前置条件）
`notarize`	`true`	使用内置公证，提交、等待、装订票据一次完成

macOS 部分还声明了 entitlements.mac.plist 权限清单，为 Electron 这类应用开了 JIT、无符号可执行内存、库验证豁免、网络客户端/服务器与用户选定文件读写等开关——每一项在文件注释里都有中文说明，是学习 Electron 权限声明的好范本。

macOS 代码签名：证书与环境变量配置

签名前需要一张Developer ID Application证书，然后通过环境变量交给 electron-builder。项目提供了体检脚本 check-sign-config.sh，会依次检查证书、环境变量与证书文件：

环境变量	必需	说明
`CSC_LINK`	✅	`.p12`证书文件路径
`CSC_KEY_PASSWORD`	✅	`.p12`证书密码
`APPLE_ID`	公证需要	Apple ID 邮箱
`APPLE_APP_SPECIFIC_PASSWORD`	公证需要	App 专用密码
`APPLE_TEAM_ID`	公证需要	你的 Team ID

运行检查：

pnpm run electron:check-sign

输出会明确告诉你哪些项已就绪、缺什么，避免签名时才发现配置不全。

公证 Notarization：为什么必须「一次到位」

公证（Notarization）是 macOS Gatekeeper 放行未进 Mac App Store 应用的关键环节。CC-Viewer 的做法非常克制：只依赖 electron-builder 的内置公证，配置里仅一行notarize: true，由它在签名后自动检测APPLE_*凭据、提交应用、等待 Apple 审批并装订票据（staple）。

配套的 notarization-config.test.js 用测试锁死了这条纪律：

断言配置中存在notarize: true；
断言不允许出现afterSign钩子；
断言不引入第二套@electron/notarize实现。

这样做的价值在于：重复提交公证会导致 Apple 端报错，而契约测试让「单一公证入口」成为不可被无意破坏的规则。

签名 + 公证由 mac-sign.sh 编排：先校验CSC_LINK/CSC_KEY_PASSWORD是否齐全（缺失立即退出），再检测公证三件套——齐全则签名后自动公证，缺省则降级为「仅签名不公证」并给出明确提示。最后执行：

pnpm run electron:sign # 等价于 build + electron-builder --mac

Windows 与 Linux 产物同样由同一份配置产出：NSIS 安装包（可自选安装目录）与 AppImage。

验证与分发：产物在哪里

构建完成后，所有安装包位于apps/electron/electron-dist/。验证签名是否生效可以用：

codesign -dv --verbose=4 "CC Viewer.app" spctl -a -vvv "CC Viewer.app"

另外值得一提的是仓库自带的 cc-viewer.rb Homebrew 公式：它为 CLI 版安装了一个自定义 shell 包装器，强绑 Homebrew 的 node 而不是 PATH 中的 node——因为node-pty原生绑定跨 Node 大版本会 ABI 失配。这个细节解释了为什么打包时必须开启npmRebuild。

常见问题速查

只想签名不想公证？不设置APPLE_*三个变量即可，脚本会自动降级并提示。
构建报原生模块错误？检查npmRebuild: true是否被改动，并保持 package.json 中electron与electron-builder版本配套。
想本地调试桌面壳？直接pnpm run electron:dev，外壳会自动识别仓库开发布局。

从 Web 到桌面，CC-Viewer 用「拼装暂存目录 + 单一打包配置 + 契约测试」把 Electron 打包、macOS 代码签名与公证收敛成一条可重复、可验证的流水线——这正是开源项目桌面分发值得借鉴的工程实践。