【剪映小助手-客户端】构建与部署

构建与部署

简介

本指南面向 capcut-mate 桌面客户端的构建与部署，覆盖 Electron 应用的构建流程、打包配置、发布策略、版本管理、自动更新机制与签名验证流程，并提供开发环境配置、调试工具使用与生产环境部署的最佳实践。文档同时涵盖跨平台兼容性处理、安装包优化与分发渠道管理的实操建议。

项目结构

capcut-mate 的桌面客户端位于 desktop-client 目录，采用"主进程 + 预加载桥接 + React 前端"的典型 Electron 架构：

主进程负责窗口生命周期、系统集成与 IPC 注册
预加载脚本通过 contextBridge 暴露受控 API 给渲染进程
React 前端通过 Vite 构建并输出到 ui 目录供主进程加载
nodeapi 子模块封装下载、日志、配置等业务逻辑
scripts 目录包含 electron-builder 的多套打包配置与版本更新脚本
.github/workflows 提供 CI 流水线，支持 Windows 与 macOS 平台的安装包与绿色包构建、上传与发布

桌面客户端
主进程 main.js
预加载 preload.js
React 前端(Vite)
NodeAPI(download.js, ipcHandlers.js, logger.js)
打包配置(electron-builder.config.js, green.config.js)
版本更新(update-version.js)
macOS 权限(entitlements.mac.plist)

核心组件

构建脚本与打包配置
- desktop-client/package.json 定义了开发、前端构建、打包与安装包生成脚本，以及 electron-builder 与 electron-packager 依赖
- scripts/electron-builder.config.js 与 scripts/electron-builder-green.config.js 分别定义了标准安装包与绿色便携包的打包规则
主进程与窗口管理
- main.js 负责窗口创建、开发/生产模式切换、异常捕获与 IPC 初始化
预加载与 API 暴露
- preload.js 通过 contextBridge 暴露受限 API，供 React 前端调用
NodeAPI 业务逻辑
- nodeapi/ipcHandlers.js 注册 IPC 处理函数，连接下载、日志、配置、历史记录等功能
- nodeapi/download.js 实现草稿下载、路径解析、重试机制、日志与历史记录写入
- nodeapi/logger.js 基于 log4js 的日志配置，输出到用户数据目录
macOS 权限与沙箱
- assets/entitlements.mac.plist 配置沙箱与文件夹访问权限
前端服务封装
- web/src/services/electronService.js 提供浏览器与 Electron 环境的双态 API 封装
CI/CD 与版本管理
- .github/workflows/desktop-client-dev.yml 定义多平台构建矩阵、安装包与绿色包产物上传、GitHub Release 发布
- scripts/update-version.js 从 GitHub Ref 提取语义化版本并更新 package.json

架构总览

下图展示了从 CI 触发到产物发布的整体流程，以及主进程、预加载、前端与 NodeAPI 的交互关系。
"GitHub Release" "产物(dist)" "macOS 构建" "Windows 构建" "electron-builder" "desktop-client/package.json 脚本" "GitHub Actions" "GitHub Release" "产物(dist)" "macOS 构建" "Windows 构建" "electron-builder" "desktop-client/package.json 脚本" "GitHub Actions" 触发构建矩阵执行安装包/绿色包构建生成 exe/dmg/zip 生成 dmg/zip 输出安装包与绿色包上传并发布

详细组件分析

构建脚本与打包配置

package.json 脚本职责
- 开发与前端：启动主进程、前端开发服务器、前端构建
- 传统打包：electron-packager 生成各平台二进制
- 安装包打包：electron-builder 生成 NSIS(dmg) 安装包，支持 x64/arm64
- 绿色包打包：electron-builder 生成 zip 包，便于便携使用
electron-builder 配置要点
- Windows：NSIS 安装器、自定义产物命名、禁用签名算法（示例）
- macOS：dmg 多架构目标、硬硬化运行时、Gatekeeper 放行、entitlements 配置
- 文件过滤：排除 web、dist、脚本与配置文件，仅打包必要资源
- 绿色包：显式包含 node_modules/ui/nodeapi/assets 等运行所需资源
版本更新脚本
- 从 GITHUB_REF 提取 tag，校验语义化版本，写回 package.json

否
是
否
是
开始
检查 GITHUB_REF 是否为 tag
跳过版本更新
解析语义化版本
版本有效?
退出并报错
读取 package.json
更新 version 字段
写回 package.json
结束

主进程与窗口管理

窗口创建与图标适配：根据平台选择 icns/ico/png
开发/生产模式：开发模式加载本地 Vite 服务，生产模式加载 ui/index.html
安全配置：禁用 Node 集成、启用上下文隔离、预加载脚本、硬件加速
异常处理：捕获未捕获异常，macOS 权限错误弹窗提示
生命周期：窗口关闭与 macOS Dock 行为

"NodeAPI 下载" "React 前端" "预加载脚本" "主窗口" "Electron App" "NodeAPI 下载" "React 前端" "预加载脚本" "主窗口" "Electron App" alt [开发模式] [生产模式] createWindow() 注入预加载脚本加载 http : //localhost : 9000 加载 ui/index.html IPC 调用(下载/日志/配置) 返回结果与事件

预加载与 API 暴露

通过 contextBridge.exposeInMainWorld 暴露受限 API，包括文件保存、草稿下载、日志、消息框、外部链接、配置、历史记录等
渲染进程通过 window.electronAPI 调用，避免直接暴露 Node/Electron 能力

NodeAPI 业务逻辑

IPC 处理器注册：统一在 ipcHandlers.js 中集中注册，便于维护
下载流程：解析草稿 URL -> 选择目标目录 -> 逐文件下载（含重试）-> 写入日志与历史记录 -> 可选打开目录
日志系统：基于 log4js，按日切割，保留 7 天备份
权限与错误处理：目录权限校验、网络错误分类、UI 反馈与日志记录

是
是
否
否
开始下载
读取配置/选择目录
解析目标文件路径
遍历文件列表
带重试下载(最多3次)
成功?
写入成功日志
写入失败日志
下一个文件
写入历史记录
完成

前端服务封装与跨环境兼容

electronService.js 提供浏览器与 Electron 环境的双态 API 封装：在浏览器环境提供空实现或模拟行为，在 Electron 环境调用 window.electronAPI
保证前端在浏览器中也能正常运行，便于测试与演示

CI/CD 与发布策略

构建矩阵：Windows、macOS arm64、macOS x64 三平台并行
步骤：安装依赖、前端构建、版本更新、打包、绿色包、上传产物、发布
产物：安装包与绿色包，按平台命名；发布到 GitHub Releases

"GitHub Release" "dist 目录" "electron-builder" "npm 脚本" "Workflows" "GitHub Release" "dist 目录" "electron-builder" "npm 脚本" "Workflows" 执行 build-win/mac/mac-x64 生成安装包输出 exe/dmg/zip 执行 green 打包生成 zip 输出 zip 上传并发布

版本管理与自动更新机制

版本来源：GitHub Tag（refs/tags/vX.Y.Z 或 refs/tags/X.Y.Z），由 update-version.js 读取并写回 package.json
自动更新：当前仓库未见内置 autoUpdater 配置，若需在线更新可在 electron-builder 配置中启用 NSIS Web 或 Squirrel.Windows 更新通道，并在主进程引入 autoUpdater 逻辑

签名验证与 macOS 权限

macOS 签名：electron-builder 配置中可启用签名与公证流程（当前配置示例禁用签名算法，实际应按团队证书配置）
权限与沙箱：entitlements.mac.plist 启用沙箱与用户文件夹读写权限，满足下载与草稿目录访问需求

依赖关系分析

主进程依赖
- Electron 核心 API（app、BrowserWindow、dialog、shell）
- 预加载脚本与 IPC 处理器
- NodeAPI 下载与日志模块
打包与构建
- electron-builder 与 electron-packager
- Vite 前端构建，输出到 ui 目录
CI 依赖
- GitHub Actions、nodejs 22、npm ci 缓存

main.js
preload.js
ipcHandlers.js
download.js
logger.js
electron-builder.config.js
electron-builder-green.config.js
electron-builder
dist 产物

性能考量

窗口与渲染
- 启用硬件加速、上下文隔离、禁用 Node 集成，降低安全风险并提升性能
下载与 IO
- 使用流式下载处理大文件，限制并发，增加重试与断点容错
- 日志轮转与上限控制，避免磁盘占用过大
打包体积
- 使用 electron-builder 的 files 过滤，排除开发与临时文件
- 绿色包显式包含运行所需资源，减少缺失导致的二次打包

故障排查指南

权限错误（macOS）
- 现象：未捕获异常弹窗提示权限不足
- 处理：检查系统偏好设置 > 安全性与隐私 > 隐私 > 文件夹访问
目录无读写权限
- 现象：选择目录后仍提示权限不足
- 处理：更换目录或授予对应文件夹读写权限
下载失败
- 现象：部分文件多次重试后失败
- 处理：检查网络、URL 可达性、磁盘空间与目标目录权限
安装包无法运行（macOS）
- 现象：提示损坏或无法打开
- 处理：确认签名与公证流程、Gatekeeper 放行、entitlements 配置正确

结论

本指南梳理了 capcut-mate 桌面客户端的构建与部署全流程，明确了脚本职责、打包配置、CI 策略与版本管理方式。结合 macOS 权限与沙箱配置、下载与日志模块、以及前端跨环境兼容封装，可稳定产出 Windows 与 macOS 平台的安装包与绿色包，并通过 GitHub Release 进行分发。后续可按需接入自动更新与签名公证流程，进一步完善发布体验。

附录

开发环境配置
- 安装 Node.js 22 与 npm ci，分别安装 desktop-client 与 web 子目录依赖
- 使用 npm run start 启动主进程，npm run web:dev 启动前端开发服务器
调试工具
- 开发模式下自动打开 DevTools，日志输出到用户数据目录下的日志文件
生产环境部署最佳实践
- 使用 electron-builder 生成安装包并上传至发布渠道
- 为 macOS 配置签名与公证，确保 Gatekeeper 放行
- 为 Windows 配置代码签名，提升用户信任度
- 使用绿色包提供便携分发选项，降低安装门槛

接口文档： https://docs.jcaigc.cn
效果案例： https://www.jcaigc.cn/workflow
开源仓库： https://github.com/Hommy-master/capcut-mate