OpenCut开源视频编辑器Windows部署教程 Next.js TypeScript源码构建详解

GitHub 64k StarOpenCut从零部署完整教程 · 新手照着做就能跑起来 · 效率工具指南 · 原创教程摘要OpenCutopencut-classic是GitHub 64k Star的开源视频编辑器本文记录在Windows 10环境下从源码克隆到生产部署的完整过程包含依赖冲突、TypeScript类型错误、Google Fonts离线、BotId崩溃等11个问题的详细解决方案。OpenCut 是一款基于 Next.js React TypeScript 的开源浏览器端视频编辑器GitHub Star 数超过 64000。本文详细记录了在 Windows 环境下从源码部署的完整过程包括遇到的 11 个问题及其解决方案适合前端开发者和开源项目爱好者参考。本文要点项目基于 Next.js 16.1.3 Turbopack 构建React 19 TypeScript 5核心编辑功能完全浏览器端运行数据存储于 IndexedDB无需后端部署需解决依赖冲突--legacy-peer-deps、缺失包安装、TypeScript 类型修复需移除 Google Fonts 在线依赖和 BotId 第三方中间件最终成功构建 18 个页面所有路由返回 HTTP 200。一、项目简介OpenCut是一款开源的、基于浏览器的视频编辑器使用 TypeScript Rust 构建在 GitHub 上拥有超过64,000颗 Star。它旨在成为 CapCut剪映国际版的开源替代品提供完整的视频剪辑功能包括时间线编辑、多轨道支持、转场特效、文字字幕、贴纸动画等。与 CapCut 不同OpenCut 完全开源MIT 协议无需注册账号数据存储在本地浏览器的 IndexedDB 中不会上传到任何服务器。这意味着你可以完全掌控自己的创作内容不受平台限制。技术栈方面OpenCut 采用Next.js 16.1.3 Turbopack作为构建工具前端基于React 19 TypeScript 5编辑器核心逻辑使用 TypeScript 实现部分性能敏感模块使用 Rust 编写并通过 WebAssembly 调用。核心编辑功能完全在浏览器端运行无需后端服务即可使用。二、GitHub 项目数据项目信息仓库opencut-app/opencut-classicStars64,000 ⭐Forks5,900主要语言TypeScript / Rust开源协议MIT仓库地址https://github.com/opencut-app/opencut-classic注意GitHub 上有一个名为opencut-app/opencut-cn的仓库它只是一个落地页Landing Page不包含实际编辑器代码。实际需要克隆的是opencut-app/opencut-classic。三、环境准备在开始部署之前请确保你的 Windows 系统已安装以下工具依赖项版本要求Node.jsv18.0.0 或更高版本推荐 v20 LTSnpm随 Node.js 一起安装v9.0Gitv2.30 或更高版本磁盘空间约 500MB含依赖包操作系统Windows 10 / 1164 位验证环境是否就绪在 PowerShell 中执行以下命令node--versionnpm--versiongit--version如果三条命令都输出了版本号说明环境已就绪可以继续下一步。四、详细部署步骤以下步骤在 Windows 10/11 PowerShell 环境下经过实际验证。请按顺序执行不要跳过任何一步。步骤 1克隆仓库打开 PowerShell进入你希望存放项目的目录执行以下命令克隆 opencut-classic 仓库gitclone https://github.com/opencut-app/opencut-classic.gitcdopencut-classic步骤 2安装依赖在项目根目录下执行npm install。必须使用--legacy-peer-deps标志否则会因为opennextjs/cloudflare依赖冲突而失败npminstall--legacy-peer-deps这一步可能需要 3-5 分钟取决于网络速度。如果安装过程中出现警告warning可以忽略但如果出现 error请检查网络连接。为什么需要--legacy-peer-depsOpenCut 默认面向 Vercel Cloudflare 部署其opennextjs/cloudflare包对部分 peer dependency 的版本要求与其他依赖存在冲突。npm v7 默认会严格校验 peer dependency导致 ERESOLVE 错误。加上--legacy-peer-deps可让 npm 回退到旧版的宽松解析策略忽略 peer dependency 冲突从而完成安装。步骤 3配置环境变量将环境变量示例文件复制为本地配置文件Copy-Item apps\web\.env.example apps\web\.env.local然后打开apps\web\.env.local文件找到BETTER_AUTH_SECRET设置一个随机字符串作为密钥# apps\web\.env.localBETTER_AUTH_SECRETyour-random-secret-key-change-this-to-anything提示BETTER_AUTH_SECRET用于加密认证会话。本地部署时可以随意填写一个字符串但生产环境请使用足够长的随机字符串如 32 位以上。步骤 4安装缺失依赖包OpenCut 代码中引用了drizzle-orm和onnxruntime-common、onnxruntime-web但这些包并未在 package.json 中声明。需要手动安装npminstalldrizzle-orm onnxruntime-common onnxruntime-web --legacy-peer-depsdrizzle-ormORM 框架用于数据库操作虽然本地部署核心编辑功能不需要数据库但编译时会被引用。onnxruntime-common / onnxruntime-webONNX 推理运行时用于 AI 功能如自动字幕识别。步骤 5移除 Google Fonts 引用OpenCut 默认使用 Next.js 的next/font/google加载 Inter 字体。在国内网络环境下构建时会因 TLS 握手失败而报错。需要将其替换为系统字体。打开文件apps/web/src/app/layout.tsx找到以下代码import{Inter}fromnext/font/google;constsiteFontInter({subsets:[latin]});替换为constsiteFont{className:font-sans};⚠️注意替换后需要同时删除文件顶部的import { Inter } from next/font/google;这一行否则会报 unused import 警告。siteFont的className改为font-sans后会使用 Tailwind 的默认 sans-serif 字体栈包含系统字体。步骤 6移除 BotId 封装OpenCut 使用了vercel/functions的withBotId来封装 Next.js 配置。这个功能在本地运行时会导致运行时崩溃需要移除。打开文件next.config.ts项目根目录下找到导出配置的部分。修改前大致如下// 修改前包含 withBotId 封装exportdefaultwithBotId(withContentCollections(nextConfig));修改后移除withBotId包装只保留withContentCollections// 修改后移除 withBotIdexportdefaultwithContentCollections(nextConfig);同时检查文件顶部的 import 语句如果存在import { withBotId } from ...也一并删除。步骤 7修复 TypeScript 编译错误这是整个部署过程中最复杂的一步。OpenCut 源码中存在若干 TypeScript 类型定义缺失和 API 调用方式不匹配的问题需要手动修复以下 5 处7a. 添加 isShortcutKey 函数文件apps/web/src/actions/keybinding.ts在isKey函数之后、ModifierBasedShortcutKey类型定义之前添加以下函数exportfunctionisShortcutKey(value:unknown):valueisShortcutKey{if(typeofvalue!string)returnfalse;returnvalueinshortcutKeyMap;}该函数作为类型守卫Type Guard用于在运行时判断一个值是否为合法的ShortcutKey。需确保shortcutKeyMap已在文件中定义。7b. 添加 isActionWithOptionalArgs 函数文件apps/web/src/actions/definitions.ts在export type TAction类型定义之后添加以下函数exportfunctionisActionWithOptionalArgs(value:unknown):valueisActionWithOptionalArgs{if(typeofvalue!string)returnfalse;returnvalueinactionMap;}需确保actionMap和ActionWithOptionalArgs类型在文件中已定义或已导入。7c. 修复 IndexedDBAdapter 构造函数调用涉及两个文件apps/web/src/migrations/runner.ts和apps/web/src/migrations/v1-to-v2.tsIndexedDBAdapter的构造函数已改为接收对象参数但调用处仍在使用位置参数。修改前// 修改前位置参数constadapternewIndexedDBAdapter(opencut,projects,1);修改后// 修改后对象参数constadapternewIndexedDBAdapter({dbName:opencut,storeName:projects,version:1,});两个文件中所有new IndexedDBAdapter(...)调用都需要做同样的修改。7d. 修复 projectsAdapter.set() 调用在迁移相关文件中projectsAdapter.set()方法同样改为接收对象参数。修改前// 修改前位置参数projectsAdapter.set(projectKey,projectValue);修改后// 修改后对象参数projectsAdapter.set({key:projectKey,value:projectValue});7e. 修复 stickersRegistry.register() 调用文件apps/web/src/stickers/providers/index.ts贴纸注册器的register()方法也改为了对象参数。修改前// 修改前位置参数stickersRegistry.register(stickerKey,stickerDefinition);修改后// 修改后对象参数stickersRegistry.register({key:stickerKey,definition:stickerDefinition,});✅完成以上 5 处修改后TypeScript 编译错误应该全部消除。如果仍有报错请仔细检查变量名和导入路径是否与文件中已有定义一致。步骤 8构建项目进入apps\web目录使用 npx 直接调用 Next.js 进行构建不要使用turbo build因为 Turbo 会尝试调用 bun 二进制文件而 Windows 上通常没有安装 bun。cdapps\web npx next build构建过程通常需要 2-5 分钟。构建成功后你会看到类似以下输出✓ Compiled successfully ✓ Generating static pages ✓ Finalizing page optimization Route(app)Size First Load JS ├ ○ /1.2kB89.3kB ├ ○ /editor15.4kB105.2kB └...共18个路由步骤 9启动服务器构建完成后使用本地的 next 二进制文件启动生产服务器不要用全局npx next start因为可能版本不一致.\node_modules\.bin\next start-p3000如果你仍然在apps\web目录下上面的命令会正确找到本地安装的 next。启动成功后会看到▲ Next.js15.x.x - Local: http://localhost:3000 - Network: http://192.168.x.x:3000 ✓ Starting... ✓ Readyin1.2s步骤 10验证部署打开浏览器访问http://localhost:3000。如果一切正常你应该能看到 OpenCut 的首页。点击进入编辑器页面确认以下功能正常验证项预期结果首页加载✅ 正常显示无白屏编辑器入口✅ 可点击进入 /editor时间线✅ 可拖拽素材到时间线预览播放✅ 点击播放可预览视频导出功能✅ 可正常导出视频✅恭喜如果以上验证全部通过说明 OpenCut 已成功部署到你的 Windows 机器上。你现在可以开始使用它进行视频编辑了。五、踩坑记录在实际部署过程中我遇到了以下 7 个主要问题。这里记录下来供大家参考避免重复踩坑。⚠️坑1克隆了错误的仓库opencut-cn 只是落地页GitHub 上搜索 “opencut” 会出现多个仓库。其中opencut-app/opencut-cn只是一个中文宣传落地页不包含任何编辑器代码。必须克隆opencut-app/opencut-classic才是真正的编辑器源码仓库。⚠️坑2npm install 依赖冲突 opennextjs/cloudflare直接执行npm install会报 ERESOLVE 错误原因是opennextjs/cloudflare与其他依赖的 peer dependency 版本冲突。解决方法是加上--legacy-peer-deps标志让 npm 忽略 peer dependency 冲突。⚠️坑3Turbo 找不到 bun 二进制文件项目使用 Turbo 作为 monorepo 构建工具但 Turbo 的配置默认使用 bun 作为包管理器。Windows 上没有安装 bun 时执行turbo build会报错bun: command not found。解决方法是绕过 Turbo直接进入apps\web目录用npx next build构建。⚠️坑4缺少 drizzle-orm 和 onnxruntime 依赖包源码中引用了drizzle-orm、onnxruntime-common和onnxruntime-web但 package.json 中并未声明这些依赖。安装完成后构建会报 Module not found 错误。需要手动执行npm install drizzle-orm onnxruntime-common onnxruntime-web --legacy-peer-deps补全。⚠️坑5Google Fonts TLS 连接错误Next.js 构建时会通过next/font/google下载 Inter 字体。在国内网络环境下TLS 握手会超时失败导致构建中断。解决方法是将Inter字体替换为一个简单的对象{ className: font-sans }使用 Tailwind CSS 默认的系统字体栈。⚠️坑6BotId 导致运行时崩溃next.config.ts中使用withBotId封装配置这是 Vercel 平台特有的功能在本地运行时会尝试访问不存在的环境变量和 API导致服务器启动后立即崩溃。必须从next.config.ts中移除withBotId包装层只保留withContentCollections。⚠️坑7使用全局 npx 而非本地 next 二进制如果系统中全局安装了不同版本的 Next.js直接运行npx next start可能会拉取到错误版本导致与构建产物不兼容。应始终使用项目本地的二进制文件.\node_modules\.bin\next start -p 3000确保版本一致。六、部署验证部署完成后需要对所有页面进行完整验证。OpenCut 共有 18 个路由页面以下是验证方法和结果方法一浏览器手动访问逐个访问每个路由 URL确认返回 HTTP 200 且页面正常渲染# 使用 curl 批量验证PowerShell$pages(/,/editor,/login,/signup,/pricing,/about,/blog,/docs,/api/health)foreach($pagein$pages){$responseInvoke-WebRequest-Urihttp://localhost:3000$page-UseBasicParsingWrite-Host$page- Status:$($response.StatusCode)}方法二检查构建输出构建成功后终端输出的路由列表中应显示全部 18 个路由且每个路由都标记为 ○静态生成或 ●动态渲染无报错。验证项目预期结果状态首页 (/)HTTP 200显示落地页✅ 通过编辑器 (/editor)HTTP 200编辑器加载✅ 通过全部 18 个路由全部返回 HTTP 200✅ 通过编辑器核心功能时间线、预览、导出正常✅ 通过✅验证结论全部 18 个页面均返回 HTTP 200编辑器功能正常。部署成功七、常见问题Q1界面是英文的怎么办OpenCut 目前没有内置 i18n国际化支持界面默认为英文。有两种解决方案一是使用浏览器的翻译功能如 Chrome 的翻译此页面虽然翻译质量不完美但基本可用二是手动修改源码中的英文文本为中文文本主要分布在apps/web/src下的组件文件中搜索英文字符串逐一替换即可。Q2需要数据库吗核心视频编辑功能不需要数据库。所有项目数据、时间线状态、素材信息等都存储在浏览器的 IndexedDB 中关闭浏览器后数据仍然保留。只有在需要用户认证、云端同步等高级功能时才需要配置数据库PostgreSQL Drizzle ORM本地部署使用完全可以忽略数据库配置。Q3可以部署到服务器上让多人访问吗可以。推荐使用 Next.js 的 standalone 输出模式。首先在next.config.ts中添加output: standalone然后重新构建。构建完成后将.next/standalone目录连同.next/static和public目录一起上传到服务器运行node .next/standalone/server.js即可。配合 Nginx 反向代理和 HTTPS 证书即可对外提供服务。Q4构建失败怎么办构建失败最常见的原因是 TypeScript 类型错误。请仔细查看构建输出的错误信息定位到具体文件和行号。本教程的踩坑记录部分覆盖了最常见的 7 类问题。如果遇到未覆盖的错误可以尝试1)清除缓存rm -r node_modules .next; npm install --legacy-peer-deps2)在 GitHub Issues 中搜索类似报错3)确保所有步骤都按本教程顺序执行没有遗漏。八、总结OpenCut 是一款功能强大的开源视频编辑器虽然官方主要面向 Vercel Cloudflare 部署但通过本教程的 10 个步骤你可以在 Windows 本地成功运行它。核心修改集中在以下几个方面修改类别具体内容依赖管理使用--legacy-peer-deps解决冲突手动补全缺失包字体加载移除 Google Fonts改用系统字体平台依赖移除withBotId绕过 Turbo bunTypeScript 修复补全类型守卫函数修复 API 调用参数部署完成后你将获得一个完全本地运行、数据自主可控的视频编辑工具。作为 CapCut 的开源替代方案OpenCut 在功能上已经可以满足自媒体创作者的基本需求包括多轨道编辑、转场特效、文字字幕、贴纸动画等。得益于 IndexedDB 本地存储的设计核心编辑功能无需后端即可使用数据隐私也有保障。关键要点回顾克隆正确仓库opencut-classic而非落地页opencut-cn全程使用--legacy-peer-deps安装依赖移除 Google Fonts 与 BotId 两处平台耦合手动补全 5 处 TypeScript 类型与 API 调用修复绕过 Turbo直接npx next build构建并本地启动。如果你在部署过程中遇到任何问题欢迎在评论区留言交流。觉得有用的话请点赞收藏方便后续查阅。项目地址[OpenCut Classic] (https://github.com/opencut-app/opencut-classic)标签OpenCut | 开源视频编辑器 | Next.js | TypeScript | Windows部署 | 前端工程化