Node.js 集成

简介

本文件面向开发者，系统性阐述 capcut-mate 桌面客户端中 Node.js 与 Electron 的集成方案，重点覆盖以下方面：

预加载脚本如何安全地向渲染进程暴露受限的 Node.js 能力
下载管理、文件系统操作与外部工具调用的实现细节
新增：triggerDirectoryScan 目录扫描功能，增强 Adobe Premiere Pro 自动检测能力
日志记录、错误处理与异步流程管理
性能优化策略与扩展集成指导原则

该应用采用主进程负责系统级能力（文件系统、网络请求、对话框、外部浏览器），渲染进程通过受控接口调用，确保安全与可维护性。

项目结构

桌面客户端采用"主进程 + 预加载桥接 + 渲染进程"的三层架构：

主进程：创建 BrowserWindow、注册 IPC 处理器、管理窗口生命周期与系统交互
预加载脚本：通过 contextBridge 暴露有限 API 给渲染进程
渲染进程：React 页面与组件，通过 electronService 统一封装调用

graph TB
subgraph "主进程"
M["main.js<br/>创建窗口/注册IPC"]
D["nodeapi/download.js<br/>下载/文件系统/日志/目录扫描"]
L["nodeapi/logger.js<br/>日志配置"]
H["nodeapi/ipcHandlers.js<br/>IPC处理器"]
end
subgraph "预加载"
P["preload.js<br/>contextBridge 暴露API"]
end
subgraph "渲染进程"
S["web/src/services/electronService.js<br/>统一API封装"]
DL["pages/Download/index.jsx<br/>下载入口"]
HL["pages/History/index.jsx<br/>历史记录"]
LB["components/LogModule.jsx<br/>日志展示"]
BTN["components/DownloadButton.jsx<br/>下载按钮"]
end
M --> H
H --> D
D --> L
M --> P
P --> S
S --> DL
S --> HL
DL --> LB
DL --> BTN

核心组件

日志模块：基于 log4js，按日期切割日志文件，同时输出到控制台，便于开发调试与生产排障
下载模块：封装草稿解析、目录选择、批量下载、重试机制、日志与历史记录持久化
新增：triggerDirectoryScan 目录扫描模块：通过系统工具触发文件系统变更通知，实现 Adobe Premiere Pro 的自动检测
IPC 处理器：集中注册主进程侧的异步处理函数，供预加载脚本通过 ipcRenderer.invoke 调用
预加载桥接：通过 contextBridge.exposeInMainWorld 暴露受控 API，避免直接注入全局变量
渲染服务层：electronService 统一封装 Electron 与浏览器环境差异，保证跨环境一致性

架构总览

下图展示了从渲染进程发起下载请求到主进程执行系统操作的端到端流程，包括新增的目录扫描功能：

sequenceDiagram
participant UI as "渲染进程<br/>Download/index.jsx"
participant SVC as "服务层<br/>electronService.js"
participant PRE as "预加载<br/>preload.js"
participant IPC as "IPC处理器<br/>ipcHandlers.js"
participant DL as "下载模块<br/>download.js"
participant FS as "文件系统/对话框<br/>Electron APIs"
participant SCAN as "目录扫描<br/>triggerDirectoryScan"
UI->>SVC : "saveFile(选项)"
SVC->>PRE : "invoke('save-file', 选项)"
PRE->>IPC : "ipcMain.handle('save-file')"
IPC->>DL : "downloadFiles(选项, 父窗口)"
DL->>FS : "选择目录/写文件/打开目录"
DL->>SCAN : "triggerDirectoryScan(草稿目录)"
SCAN->>FS : "Windows : robocopy<br/>macOS : rsync"
SCAN-->>DL : "触发文件系统变更通知"
DL-->>IPC : "返回结果"
IPC-->>PRE : "返回结果"
PRE-->>SVC : "返回结果"
SVC-->>UI : "返回结果"
DL-->>UI : "通过 onFileOperationLog 推送实时日志"

详细组件分析

预加载与安全桥接

通过 contextBridge.exposeInMainWorld 将有限 API 暴露到 window.electronAPI
仅暴露明确的 IPC 调用（如 save-file、get-url-json-data、get-download-log 等）
渲染进程通过 ipcRenderer.invoke 发起调用，主进程在 ipcMain.handle 中处理
提供监听日志事件与清理监听器的能力，避免内存泄漏

IPC 处理器与主进程职责

注册以下处理器：读取下载日志、清空日志、获取 URL JSON 数据、保存文件、显示消息框、读取配置、更新草稿路径、打开外部 URL、检测 URL 可访问性、读取历史记录
所有处理器均通过 async/await 编排，错误统一记录到日志模块
处理器接收 mainWindow 作为父窗口参数，用于弹窗与目录选择时的模态行为

下载管理与文件系统操作

目录选择：支持可选父窗口、权限校验、配置持久化
草稿解析：通过 axios 请求远程 URL，解析 JSON 并筛选包含 draft_id 的文件列表
批量下载：对每个文件执行带重试的下载流程，支持 JSON 与非 JSON 类型；写入本地文件并记录日志
新增：triggerDirectoryScan 目录扫描：下载完成后自动触发文件系统变更通知，让 Adobe Premiere Pro 无需重启即可识别新草稿
日志与历史：实时推送日志到渲染进程，同时持久化到 JSON 文件；记录历史草稿信息（含时间、ID、URL）

flowchart TD
Start(["开始"]) --> GetDir["选择/读取目标目录"]
GetDir --> Parse["解析草稿URL并获取文件列表"]
Parse --> Loop{"遍历文件"}
Loop --> |是| Target["计算目标路径并创建目录"]
Target --> Type{"JSON文件？"}
Type --> |是| WriteJson["下载JSON并修改路径后写入"]
Type --> |否| Stream["流式下载并写入"]
WriteJson --> Retry["记录日志/统计"]
Stream --> Retry
Retry --> Loop
Loop --> |否| Finish["汇总统计/记录历史/可选打开目录"]
Finish --> Scan["触发目录扫描"]
Scan --> End(["结束"])

目录扫描功能详解

新增功能：triggerDirectoryScan 函数实现了跨平台的文件系统变更通知机制，解决 Adobe Premiere Pro 需要重启才能识别新草稿的问题。

Windows 实现：使用 robocopy 工具触发 ReadDirectoryChangesW 通知
- 参数配置：递归复制、复制数据属性时间戳、重试机制、隐藏进度
- 返回码处理：0-7 表示成功，8+ 表示错误
- 临时目录清理：下载完成后自动删除 .tmp 临时目录
macOS 实现：使用 rsync 工具触发 FSEvents 变更通知
- 参数配置：归档模式（递归+保留属性），触发目录写入事件
- 变更通知：通过目录结构变更实现文件系统监控
安全检查：函数首先验证目标目录存在性，不存在则跳过执行
错误处理：捕获并记录所有系统调用错误，不影响主下载流程
平台适配：其他平台直接跳过，保持功能兼容性

日志记录与错误处理

日志：按日期切割，保留最近若干份备份；默认级别 info，同时输出到控制台
错误处理：对网络错误、权限不足、目录不可写等场景进行分类处理与用户提示
异常捕获：主进程监听 uncaughtException，针对 macOS 权限错误给出引导提示

渲染进程集成与 UI 展示

electronService：在 Electron 环境与浏览器环境之间切换实现，保证开发与打包后的一致体验
Download 页面：监听文件操作日志、触发下载、展示日志与提示
History 页面：分页展示历史记录，支持复制草稿地址
LogModule：自动滚动到最新日志条目，支持清空日志
DownloadButton：禁用状态与加载指示，提升交互反馈

依赖关系分析

主进程依赖：Electron（BrowserWindow、dialog、shell）、axios、log4js、uuid
预加载依赖：Electron（contextBridge、ipcRenderer）
渲染进程依赖：React、react-toastify、react-bootstrap、dayjs 等

graph LR
A["main.js"] --> B["nodeapi/ipcHandlers.js"]
B --> C["nodeapi/download.js"]
C --> D["nodeapi/logger.js"]
A --> E["preload.js"]
E --> F["web/src/services/electronService.js"]
F --> G["pages/Download/index.jsx"]
F --> H["pages/History/index.jsx"]

性能考量

网络请求：统一 User-Agent、设置超时、对非 JSON 文件使用流式下载，降低内存占用
文件写入：使用流式写入与错误回调删除不完整文件，避免磁盘碎片与空间浪费
新增：目录扫描性能优化：使用系统原生工具（robocopy/rsync）触发文件系统通知，避免轮询检测
日志与历史：限制日志与历史记录的最大条数，定期清理，避免无限增长
UI 响应：下载过程中禁用按钮与加载指示，避免重复提交
构建与运行：Vite 开发服务器端口固定，生产构建输出到 ui 目录，减少资源查找成本

故障排查指南

权限问题（macOS）：主进程捕获未处理异常，若出现权限错误，弹窗引导用户在系统偏好设置中授予文件夹访问权限
目录无读写权限：下载模块在选择目录后再次校验权限，失败时提示并返回空字符串
网络错误：对连接拒绝、域名不存在、服务器错误状态码进行分类处理，并记录到下载日志
新增：目录扫描失败：检查系统工具（robocopy/rsync）是否可用，查看日志中的扫描返回码
日志定位：日志文件位于 userData 目录下的按日期分割文件，同时输出到控制台
历史记录：确认历史记录 JSON 文件存在且可读，否则初始化为空数组

结论

本项目通过严格的三层架构实现了 Node.js 能力的安全集成：主进程承担系统级操作，预加载脚本提供受控 API，渲染进程通过服务层统一调用。下载模块具备完善的错误处理、重试与日志体系，配合历史记录与 UI 展示，形成闭环的用户体验。

新增的 triggerDirectoryScan 功能显著提升了用户体验：通过系统原生工具触发文件系统变更通知，Adobe Premiere Pro 可以在下载完成后自动检测到新草稿，无需重启应用程序。这一功能体现了跨平台兼容性和系统集成的最佳实践。

建议在扩展新功能时遵循"最小暴露、集中处理、统一日志"的原则，确保安全与可维护性。

附录

开发与构建
- 启动 Electron：使用 npm 脚本启动主进程
- Web 开发：Vite 开发服务器端口 9000，自动打开浏览器
- 生产构建：将 React 构建产物输出到 ui 目录，供主进程加载
扩展建议
- 新增系统操作时，优先在主进程注册 ipcMain.handle，并在预加载脚本中暴露对应 invoke 方法
- 所有异步操作使用 async/await，错误统一记录日志并反馈给用户
- 对于大文件或长耗时任务，提供进度与取消机制，避免阻塞 UI
- 新增：跨平台系统集成时，优先考虑使用系统原生工具而非轮询机制
接口文档： docs.jcaigc.cn
效果案例： www.jcaigc.cn
开源仓库： capcut-mate

【开源剪映小助手-客户端】Node.js 集成