快速开始
目录
简介
capcut-mate 是一个面向剪映（CapCut）的自动化辅助服务，提供草稿创建、媒体素材添加、字幕与特效处理、草稿保存以及视频生成等能力，并通过 OpenAPI 暴露接口。同时提供桌面客户端，帮助用户在本地管理草稿路径、下载与查看日志。
本"快速开始"指南将覆盖以下内容：
- 环境要求与安装方式（源码安装、Docker 部署、桌面客户端）
- 本地开发环境搭建、依赖安装、配置文件设置
- 首次运行验证与常见问题排查
- 新增 中英文双语支持与语言切换功能
更新 新增了中英文双语快速开始指南，用户可以通过顶部的语言切换链接在中文版和英文版之间自由切换。
项目结构
项目采用多模块组织方式：
- 后端服务：基于 Python/FastAPI 的 API 服务，路由集中在 v1 版本
- 桌面客户端：基于 Electron + React 的桌面应用，提供草稿路径设置、下载日志查看等功能
- 配置与模板：全局配置文件、草稿模板与贴纸配置
- 工具链：Dockerfile 与 docker-compose，便于容器化部署
- 新增 国际化支持：响应中间件实现语言自动检测与切换
graph TB
subgraph "后端服务"
A_main["main.py<br/>启动FastAPI应用"]
A_router["src/router/v1.py<br/>路由与业务入口"]
A_cfg["config.py<br/>运行时配置"]
A_resp["src/middlewares/response.py<br/>响应中间件语言切换"]
end
subgraph "桌面客户端"
D_main["desktop-client/main.js<br/>Electron主进程"]
D_web_pkg["desktop-client/web/package.json<br/>前端依赖"]
D_cfg_page["ConfigCenter/index.jsx<br/>草稿路径设置页"]
D_ipc["nodeapi/ipcHandlers.js<br/>IPC处理器"]
end
subgraph "部署与打包"
C_docker["Dockerfile<br/>镜像构建"]
C_compose["docker-compose.yaml<br/>服务编排"]
end
A_main --> A_router
A_main --> A_cfg
A_main --> A_resp
D_main --> D_cfg_page
D_main --> D_ipc
C_docker --> A_main
C_compose --> C_docker
核心组件
- FastAPI 应用与路由
- 应用在入口文件中创建并注册 v1 路由前缀，同时挂载中间件
- 路由集中于 v1 模块，覆盖草稿、媒体、字幕、特效、时间线、贴纸搜索等接口
-
新增 响应中间件与语言切换
- 统一响应处理中间件，支持根据 Accept-Language 请求头自动检测语言
- 支持中文（zh）和英文（en）两种语言的错误消息和响应格式
- 自动处理422参数验证错误的多语言响应
- 配置中心
- 读取环境变量，提供草稿下载 URL、下载 URL 前缀、提示 URL、模板目录、腾讯云 COS 参数等
- 桌面客户端
- Electron 主进程负责窗口生命周期与 IPC；前端 React 页面提供配置中心与下载日志展示
- 通过 IPC 与后端交互，支持更新草稿路径、读取下载日志、打开外部链接等
架构总览
后端服务通过 FastAPI 暴露 REST 接口，桌面客户端通过 Electron 与后端进行 IPC 通信，实现草稿路径设置、下载日志查看与外部链接打开等本地化功能。新增的响应中间件负责统一处理 API 响应格式和语言切换。
sequenceDiagram
participant U as "用户"
participant UI as "桌面客户端界面"
participant M as "Electron主进程"
participant S as "后端FastAPI服务"
participant RM as "响应中间件"
U->>UI : 打开"配置中心"
UI->>M : 请求读取配置
M->>S : IPC调用读取配置数据
S->>RM : 统一响应处理语言检测
RM-->>S : 返回统一格式响应
S-->>M : 返回配置草稿路径等
M-->>UI : 返回配置数据
UI-->>U : 展示当前草稿路径
U->>UI : 点击"选择草稿路径"
UI->>M : IPC请求更新草稿路径
M-->>UI : 返回更新结果
UI-->>U : 更新界面显示
详细组件分析
后端服务（FastAPI）
- 应用创建与中间件
- 创建 FastAPI 实例，注册 v1 路由前缀
- 注册准备与响应中间件，便于统一处理请求与响应
- 路由与业务
- 路由集中在 v1 模块，涵盖草稿创建/保存、媒体添加（视频/音频/图片）、字幕、特效、遮罩、关键帧、贴纸、时间线计算、URL 提取、对象与字符串互转等
- 启动
- 本地开发可通过入口文件直接运行，监听 0.0.0.0:30000
flowchart TD
Start(["启动"]) --> CreateApp["创建FastAPI应用"]
CreateApp --> IncludeRouter["注册v1路由前缀"]
IncludeRouter --> AddMW["注册中间件"]
AddMW --> AddRespMW["注册响应中间件语言切换"]
AddRespMW --> PrintRoutes["打印路由信息"]
PrintRoutes --> Run["uvicorn运行服务"]
Run --> End(["就绪"])
新增 响应中间件与语言切换
响应中间件实现了完整的语言切换功能：
-
语言检测机制
- 从 Accept-Language 请求头中提取用户的语言偏好
- 支持 zh、en 两种语言，其他语言默认返回中文
- 解析逻辑包含安全检查，防止请求头格式异常导致的问题
-
统一响应格式
- 所有成功的 API 响应都会包装为统一格式：包含 code、message 和原始数据
- 错误响应也统一为标准格式，便于前端处理
-
多语言错误处理
- 自动处理 422 参数验证错误，提供中英文混合的详细错误信息
- 支持自定义异常和通用异常的多语言响应
- 异常消息根据用户语言偏好自动切换
flowchart TD
Req["HTTP请求"] --> LangDetect["语言检测<br/>Accept-Language"]
LangDetect --> RespProc["响应处理"]
RespProc --> Success{"状态码=200?"}
Success --> |是| JSONCheck{"JSON响应?"}
Success --> |否| Non200["非200错误处理"]
JSONCheck --> |是| WrapResp["包装统一响应格式"]
JSONCheck --> |否| ReturnResp["直接返回"]
WrapResp --> LangSwitch["语言切换<br/>zh/en"]
LangSwitch --> ReturnResp
Non200 --> LangSwitch2["语言切换<br/>zh/en"]
ReturnResp --> End["响应返回"]
配置中心（config.py）
- 关键配置项
- 草稿下载 URL、下载 URL 前缀、提示 URL
- 草稿保存路径（云渲染场景需配置）
- 腾讯云 COS 参数（SecretId/SecretKey/Bucket/Region）
- API Key 启用开关
- 环境变量优先
- 通过环境变量覆盖默认值，便于容器化部署
桌面客户端（Electron + React）
- 主进程
- Electron 主进程负责窗口创建、生命周期管理、开发/生产模式加载
- 通过 IPC 注册处理器，提供读取下载日志、保存文件、打开外部链接、检测 URL 可达性、读取历史记录等能力
- 前端页面
- 配置中心页面提供草稿路径选择与展示
- 通过 electronService 适配浏览器与 Electron 环境差异
- 依赖与脚本
- 顶层 package.json 提供 Electron、打包与构建脚本
- web 子包管理 React 依赖与 Vite 构建
classDiagram
class ElectronMain {
+创建窗口()
+加载React应用()
+注册IPC处理器()
}
class IPC {
+get-download-log()
+save-file()
+open-external-url()
+check-url-access()
+get-history-record()
}
class ConfigPage {
+读取配置()
+选择草稿路径()
}
class ElectronService {
+getConfigData()
+getUrlJsonData()
+checkUrlAccess()
+openExternalUrl()
}
ElectronMain --> IPC : "注册处理器"
ElectronMain --> ConfigPage : "渲染页面"
ConfigPage --> ElectronService : "调用API"
依赖分析
- 后端依赖
- Python 版本要求：>=3.11
- 核心依赖：FastAPI、Uvicorn、requests、cos-python-sdk-v5、pymediainfo、email-validator
- 新增 国际化支持：响应中间件依赖异常处理模块提供多语言支持
- 新增 可选依赖：Windows 平台的 pywin32 和 uiautomation
- 桌面客户端依赖
- Electron、React、Vite、Bootstrap、axios、uuid、log4js 等
- 容器化
- 使用 uv 安装依赖，暴露 30000 端口，设置 PATH、HOME、UV_CACHE_DIR 等环境变量
更新 新增了国际化支持依赖，响应中间件需要异常处理模块提供的多语言错误消息。
graph LR
P["Python 3.11+"] --> F["FastAPI"]
P --> U["Uvicorn"]
P --> R["requests"]
P --> C["cos-python-sdk-v5"]
P --> M["pymediainfo"]
P --> E["email-validator"]
subgraph "国际化支持"
EX["exceptions.py<br/>多语言错误消息"]
RM["response.py<br/>语言切换中间件"]
EX --> RM
end
subgraph "可选依赖"
W1["pywin32<br/>Windows API接口"]
W2["uiautomation<br/>UI自动化库"]
end
subgraph "桌面客户端"
E2["Electron"]
R2["React/Vite"]
AX["axios"]
L["log4js"]
U2["uuid"]
end
F --> W1
F --> W2
RM --> F
性能注意事项
- 容器资源限制
- docker-compose 中设置了内存上限与 CPU 限制，避免资源争用
- 日志与缓存
- uv 缓存目录与 PATH 需正确配置，避免频繁重建导致的冷启动延迟
- 并发与中间件
- 中间件顺序影响请求处理链路，建议按现有顺序使用
-
新增 语言切换性能
- 响应中间件的语言检测开销极小，不会显著影响 API 性能
- 建议客户端在请求头中正确设置 Accept-Language，以获得最佳体验 ## 故障排查指南
- 无法访问后端服务
- 确认本地已运行入口文件，监听地址为 0.0.0.0，端口为 30000
- 若使用容器，确认端口映射与防火墙放行
- 桌面客户端无法读取配置或更新草稿路径
- 检查 Electron 主进程是否正常加载，确认 IPC 处理器已注册
- 在浏览器环境中，部分 API 会降级为模拟实现，需在桌面应用中使用
- URL 可达性检测失败
- 浏览器环境使用 axios HEAD 请求检测，若超时或失败，检查网络与目标 URL
- 权限问题（macOS）
- 主进程捕获未捕获异常，若涉及沙箱与文件夹访问权限，弹窗提示前往系统偏好设置授权
-
新增 语言切换问题
- 确认客户端请求头中包含正确的 Accept-Language 字段
- 支持的语言代码：zh（中文）、en（英文），其他语言将回退到中文
- 语言检测失败时，默认使用中文响应
-
新增 响应格式问题
- 所有 API 响应都经过统一包装，包含 code、message 字段
- 成功响应的 data 字段包含原始业务数据
- 错误响应同样包含统一格式的 code 和 message 字段
-
新增 跨平台依赖问题
- Windows 用户需要使用
pip install capcut-mate[windows]安装额外依赖 - Linux 用户应使用基础依赖安装，避免导入 Windows 特定模块
- 使用 CI/CD 测试脚本验证跨平台兼容性
- Windows 用户需要使用
结论
通过本指南，您可以在本地快速搭建 capcut-mate 的开发与运行环境，掌握三种安装方式（源码、Docker、桌面客户端），并完成首次运行验证。新增的中英文双语支持让用户可以根据自己的语言偏好选择合适的文档版本。响应中间件实现了智能的语言切换功能，确保 API 响应的统一性和多语言支持。新的可选依赖系统使 Windows 用户能够获得完整的 UI 自动化功能，而 Linux 用户也能正常安装和使用核心功能。如需进一步扩展，可参考 OpenAPI 文档与路由模块，逐步接入草稿创建、媒体添加与视频生成等能力。
附录
环境要求
- Python：>=3.11
- Node.js：用于桌面客户端（随 Electron 依赖）
- Windows/macOS：桌面客户端与剪映集成依赖
- 新增 网络浏览器：支持 Accept-Language 请求头的语言检测功能
安装与运行步骤
方式一：源码安装（本地开发）
更新 新增了跨平台安装选项和语言切换支持
1) Windows 平台（完整功能）
- 使用 uv 同步依赖或 pip 安装 Windows 特定依赖
# 使用uv安装（推荐）
uv sync
# 或者使用pip安装Windows特定依赖
pip install -e .[windows]
2) Linux 平台（基础功能）
- 使用 uv 同步依赖或 pip 安装基础依赖
# 使用uv安装（推荐）
uv sync
# 或者使用pip安装基础依赖
pip install -e .
3) 设置环境变量（可选）
- 如需自定义草稿下载 URL、下载 URL 前缀、COS 参数等，可在运行前设置对应环境变量
4) 启动后端服务
- 运行入口文件，服务监听 0.0.0.0:30000
- 使用
uvicorn main:app --host 0.0.0.0 --port 8000启动
5) 访问 OpenAPI 文档
- 通过浏览器打开后端服务地址，查看接口说明与示例
- 新增 在请求头中设置 Accept-Language: zh 或 Accept-Language: en 来测试语言切换
方式二：Docker 部署
更新 新增了跨平台 Docker 配置
1) Windows Docker（推荐用于生产）
FROM python:3.11-windowsservercore-ltsc2022
WORKDIR /app
COPY . .
# 安装完整依赖
RUN pip install -e .[windows]
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
2) Linux Docker
FROM python:3.11-slim
WORKDIR /app
COPY . .
# 安装基础依赖
RUN pip install -e .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
3) 构建镜像并启动容器
- 使用 docker-compose 启动服务，映射端口 30000，并挂载输出目录
- 在 compose 文件中设置草稿下载 URL、下载 URL 前缀、提示 URL 等
方式三：桌面客户端使用
1) 安装依赖
- 在桌面客户端根目录与 web 子目录分别安装依赖 2) 启动桌面应用
- 使用 Electron 启动主进程 3) 配置草稿路径
- 在"配置中心"页面选择剪映草稿保存路径 4) 下载与查看日志
- 通过 IPC 读取下载日志、保存文件、打开外部链接
### 首次运行验证
- 后端验证
- 访问后端服务根路径，确认返回 API 列表与路由信息
- 调用任一接口（如获取草稿列表），确认返回结构符合预期
- 新增 语言切换验证：在请求头中设置 Accept-Language: zh 或 Accept-Language: en 测试响应语言
- 桌面客户端验证
- 启动桌面应用，进入"配置中心"，选择草稿路径
- 触发 IPC 请求，确认返回成功或错误信息
- 新增 跨平台功能验证
- Windows 平台：验证 UI 自动化功能可用
- Linux 平台：验证基础 API 功能正常，UI 自动化功能降级为占位符
- 新增 国际化功能验证
- 验证响应中间件正确识别 Accept-Language 请求头
- 确认错误消息根据语言偏好自动切换
- 测试 422 参数验证错误的多语言响应 ### 常见问题与解决方案
更新 新增了语言切换和国际化相关问题的解决方案
- 服务未启动或端口占用
- 检查端口 30000 是否被占用，更换端口或释放占用进程
- 草稿路径无效
- 确认路径存在且具备写入权限；在 macOS 沙箱环境下，按提示授予文件夹访问权限
- URL 不可达
- 在浏览器环境使用 HEAD 请求检测 URL，检查网络与目标站点状态
- 容器内权限不足
- 确保挂载目录具备读写权限；核对容器内用户与缓存目录权限
-
新增 语言切换问题
- 确认客户端正确设置 Accept-Language 请求头
- 支持的语言代码：zh（中文）、en（英文），其他语言将回退到中文
- 语言检测失败时，默认使用中文响应
- 验证响应格式包含统一的 code 和 message 字段
-
新增 响应格式问题
- 所有 API 响应都经过统一包装，包含 code、message 字段
- 成功响应的 data 字段包含原始业务数据
- 错误响应同样包含统一格式的 code 和 message 字段
-
新增 Windows 依赖安装问题
- 使用
pip install capcut-mate[windows]安装 Windows 特定依赖 - 确保系统为 Windows 平台，pywin32 和 uiautomation 会被正确安装
- 使用
-
新增 Linux 依赖问题
- 使用基础依赖安装：
pip install -e . - 避免尝试安装 Windows 特定依赖，系统会自动跳过
- 使用基础依赖安装：
-
新增 跨平台兼容性测试
- 使用
python tests/test_ci_dependencies.py验证依赖安装 - 使用
python tests/test_cross_platform.py验证功能导入
- 使用
跨平台功能对比
更新 详细的跨平台功能对比表
| 功能特性 | Windows 平台 | Linux 平台 |
|---|---|---|
| ✅ 完整的视频导出自动化功能 | ✓ | ✗（需要手动导出） |
| ✅ UI界面操作支持 | ✓ | ✗（占位符功能） |
| ✅ 剪映应用控制 | ✓ | ✗（占位符功能） |
| ✅ API服务功能 | ✓ | ✓ |
| ✅ 草稿管理 | ✓ | ✓ |
| ✅ 素材处理 | ✓ | ✓ |
| ✅ 视频自动导出功能 | ✓ | ✗ |
| ✅ UI自动化操作 | ✓ | ✗ |
| ✅ Windows特定依赖 | ✓ pywin32, uiautomation | ✗ 无 |
| ✅ Linux兼容性 | ✗ 仅基础功能 | ✓ 完全兼容 |
| 新增 ✅ 多语言API支持 | ✓ 中文/英文 | ✓ 中文/英文 |
| 新增 ✅ 智能语言切换 | ✓ 基于Accept-Language | ✓ 基于Accept-Language |
语言切换使用指南
新增 详细的中英文双语支持说明
-
语言检测机制
- 服务器通过 Accept-Language 请求头自动检测用户语言偏好
- 支持的语言代码：zh（中文）、en（英文）
- 其他语言将自动回退到中文
-
API响应格式
- 所有响应都经过统一包装，包含 code、message 字段
- 成功响应：code=0，message 为对应语言的成功消息
- 错误响应：code 为对应的错误码，message 为对应语言的错误描述
使用示例
# 中文请求
curl -H "Accept-Language: zh" http://localhost:30000/openapi/capcut-mate/v1/create_draft
# 英文请求
curl -H "Accept-Language: en" http://localhost:30000/openapi/capcut-mate/v1/create_draft
-
错误处理
- 422 参数验证错误会返回详细的错误信息
- 错误信息包含字段名和具体验证失败原因
- 错误消息根据请求语言自动切换
接口文档： https://docs.jcaigc.cn
Top comments (0)