文档

米剪 (UNICUT) 开发文档

这个项目是什么

unicut 是基于开源项目 UNICUT（无界云剪）二次开发的浏览器视频剪辑器，产品名米剪 MiCut：免登录、开箱即用，把多轨剪辑、动画特效、智能处理与 AI 创作带进浏览器，工程与素材留在你的电脑里。在线版 https://cut.88531.cn/ ，仓库同时提供 Docker 私有化部署。

对开发者来说，这个仓库的价值在于它是一整套「浏览器视频剪辑」的真实工程（PixiJS/WebGL 画布 + Web Worker + FFmpeg WebAssembly），并做了面向公网开放的本地化改造：免登录、本机存储、离线可用、官方 AI 网关默认、AI 全面 BYOK，适合学习、二开或作为行业剪辑工具的底座。

技术栈

领域 技术
前端工程 React 18、TypeScript、Vite 4
UI 与状态 Semi Design、MobX、Less
画布与特效 PixiJS、WebGL、Three.js、GL Transitions
音视频处理 FFmpeg WebAssembly、MediaBunny、MP4 Muxer、Howler、Web Worker
浏览器 AI MediaPipe Tasks Vision、ONNX Runtime Web、OpenCV、Tesseract
本地数据 File System Access API、IndexedDB、Dexie
内容能力 Lottie、ECharts、GIF / APNG、JSZip、XLSX
部署 Docker、Nginx（Dockerfile + entrypoint.sh + nginx.conf）

仓库结构

unicut/
├── README.md / CHANGELOG.md / LICENSE
├── index.html / stats.html / editor.png / qrcode.jpg
├── Dockerfile / docker-compose.yml / entrypoint.sh / nginx.conf
├── package.json / yarn.lock / tsconfig.json / tsconfig.node.json / vite.config.ts
├── worker.config.js            # 音视频解码 Worker 构建配置
├── patches/                    # 依赖补丁
├── scripts/                    # 发版与工具脚本（push_registry.sh 等）
├── data-quality/               # 数据质量说明
├── docs/                       # 功能说明、产品文章与截图
├── public/
│   ├── assets/                 # FFmpeg、AI 模型、滤镜、蒙版等运行资源
│   ├── worker/                 # 音视频解码 Worker
│   └── local-ai.json.example   # 本地 AI 配置示例（严禁提交真实 Key）
└── src/
    ├── components/             # 通用组件（含 ai-settings「配置模型」弹窗）
    ├── config/                 # 运行配置与编辑器 SDK 类型
    ├── database/               # IndexedDB 数据结构
    ├── language/ / layout/ / theme/ / stores/ / utils/
    ├── server/                 # API 客户端基础层
    ├── services/               # 本地文件与工程服务
    └── pages/
        ├── editor/             # 编辑器：ai-chat / canvas / options / sources / timeline2 / plugins
        ├── home/ user/ workspace/

本地开发环境

git clone https://gitee.com/jinghui111/unicut.git
cd unicut
yarn install
yarn dev        # Vite 默认监听 3005，浏览器访问 https://localhost:3005

开发环境必须通过 localhost 或 HTTPS 访问，不建议直接双击 index.html。构建与预览：

yarn build      # 产物输出到 dist/
yarn preview    # 本地生产预览，默认 8080 端口

配置项说明

配置项 含义 取值与说明
HUB_KEY / HUB_PROJECT_ID 接入授权中心（公告 / 版本检查），写在 .env 可选，不配置不影响任何功能
src/config/index.ts 私有化部署时替换域名配置 本地 / 局域网 / 公网地址
localStorage micut.ai.config.v1 「配置模型」弹窗保存的接口地址 / API Key / 模型 只存浏览器，不上传、不落服务端
public/local-ai.json.example 本地 AI 配置示例 占位符写法，真实 Key 严禁提交
nginx 占位符（entrypoint.sh 注入） 服务端 AI 密钥注入位置 前端与仓库均不出现明文

编辑器注入点（README「二次开发与集成」，用于企业集成与品牌定制）：

配置项 用途
apiServer 接入自己的项目、素材、上传、AI 与导出服务
plugins 注册自定义编辑器元素和渲染能力
sides 增加自定义侧边栏入口和业务面板
resourcesHost 替换素材与公共资源域名
workerPath 指定媒体解码 Worker 地址
exConfig 控制 Logo、语言、项目按钮和品牌交互
movieData / appid 通过工程 JSON 或业务项目 ID 加载编辑器
saveAppCallback 保存后衔接企业内部工作流

内置的二维码元素是现成的插件参考实现：src/pages/editor/plugins/qrcode。

构建、部署与发布

镜像方式（推荐，免构建）：

docker pull gitea.88531.cn/jinghui/unicut:latest
docker run -d --name unicut -p 3006:80 -p 3005:443 gitea.88531.cn/jinghui/unicut:latest

gitea.88531.cn 是 Gitea 内置容器 Registry，免登录可拉；每次发版同步更新 latest 与 v1.0.0 两个 tag。

源码 compose 构建：docker compose up -d unicut（首次构建含前端打包，需几分钟）。端口映射 3006 → 80（HTTP）、3005 → 443（HTTPS，自签证书，首次访问需接受一次警告）；完整版另含配音服务 unicut-tts（本机 edge-tts），单独部署后用 docker compose up -d 全量启动。

发版脚本：scripts/push_registry.sh 走 docker save → skopeo 内网直推，绕过公网 nginx 单请求 413 体积上限（公网拉取不受影响）。

二次开发要点

更新记录（摘自 CHANGELOG.md）

相关链接