在 Remotion Monorepo 中本地启动 Convert 视频转换应用：从仓库构建到浏览器预览的完整实操指南

在 Remotion Monorepo 中本地启动 Convert 视频转换应用：从仓库构建到浏览器预览的完整实操指南

【免费下载链接】remotion🎥 Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion

本篇指南以仓库中的 convert 技能定义 为核心线索，讲解如何在本仓库（Remotion Monorepo）中完成环境准备、编译工作区依赖、启动@remotion/convert本地开发服务器，并在浏览器中打开 UI。读完本文，你既能按照可复现的命令跑通convert.remotion.dev的本地版本，也能理解 Convert 应用背后的包结构、Remix + Vite 构建配置与源码级实现，方便在此基础上进行调试、二次开发或 Agent 自动化调用。

一、该技能是什么：一条面向 Agent 与开发者的启动流程

在仓库 .agents/skills/convert/SKILL.md 中，定义了一个名为convert的 Agent 技能。它的 Frontmatter 明确了触发条件与目标：

--- name: convert description: Start the local @remotion/convert app and open it in the Codex browser. Use when the user invokes /convert or $convert, asks to launch convert.remotion.dev locally, or wants to inspect the Convert package UI. ---

从描述可以看出，该技能服务的对象是仓库中真实的 packages/convert 包——一个可以在本地启动的“视频转换器”Web 应用。触发方式包括显式调用/convert、$convert，或当用户要求本地启动convert.remotion.dev、查看 Convert 包 UI 时自动激活。

技能文档将其工作拆解为“Prepare → Launch → Verify”三步，本质是一个最小可执行的本地启动清单：

1. 在仓库根目录执行依赖安装与编译（bun i && bun run build）；
2. 在packages/convert目录下启动 Vite/Remix 开发服务器（bun run dev）；
3. 保持进程运行，从终端输出中解析本地 URL，并交由浏览器工具打开。

值得注意的是，该技能并非孤立存在。仓库根 package.json 中提供了checkskills、syncskills等脚本（内部调用packages/skills/scripts/sync-agent-skills.ts、validate-links.ts等），用于同步与校验.agents/skills/**/SKILL.md这类技能文件；.agents/skills/convert/agents/openai.yaml还提供了面向 Agent 的接口描述（display_name 为 "Convert App"，default_prompt 为 “Use $convert to build Remotion and open the Convert app locally.”）。这表明它是一套与仓库同步维护、可被 Agent 工具系统识别和调用的一等公民工作流。

二、Convert App 是什么：Mediabunny 驱动的浏览器端视频转换器

在深入启动流程前，先建立对目标应用的整体认知。

packages/convert/README.md 只有短短两段话，却给出了最准确的产品定位：

The source code for remotion.dev/convert, a fast video converter powered by Mediabunny.

也就是说，@remotion/convert是线上remotion.dev/convert（其 package.json 的homepage字段亦指向https://convert.remotion.dev）的源码所在，其核心能力是基于 Mediabunny 驱动的视频转换。该包在 packages/convert/package.json 中标注为private、@remotion/convert、版本号与 monorepo 保持一致，并以 “Video conversion tool - convert.remotion.dev” 作为描述，遵循 MIT 许可。

从源码结构与依赖看它的能力边界

packages/convert/package.json 的依赖项直接揭示了功能构成：

进一步看 packages/convert/app/routes 的路由文件，可以清晰地枚举出应用提供的工具页面：

• _index.tsx——应用首页 / 落地页；
• convert._index.tsx、convert.$action.tsx——核心“转换”工作流；
• trim._index.tsx、trim.$format.tsx——视频裁剪（Trim）；
• crop._index.tsx、crop.$format.tsx——画面裁剪（Crop）；
• rotate._index.tsx、rotate.$format.tsx——旋转；
• mirror._index.tsx、mirror.$format.tsx——镜像翻转；
• resize._index.tsx、resize.$format.tsx——尺寸调整；
• timing-editor._index.tsx——时间轴 / 时序编辑；
• transcribe._index.tsx——语音转字幕/转写（对应用了@remotion/whisper-webgpu这一 WebGPU 端 Whisper 实现）；
• probe._index.tsx——媒体探测（查看容器、流与元数据）；
• report._index.tsx——问题反馈（结合@mux/upchunk依赖推断其支持上传媒体样本）。

$format参数化路由的存在说明：裁剪、旋转等操作针对不同输出格式（如 mp4、webm 等）存在独立页面分支。

从工程引用看，packages/convert/tsconfig.json 将../media-parser、../webcodecs、../design作为 TypeScript 工程引用，并且 lib 中启用了WebWorker与 DOM WebCodecs 相关类型。这印证了 Convert 的转换管线与仓库内 packages/media-parser（媒体解析）、packages/webcodecs（基于 WebCodecs 的浏览器端编码）紧密耦合——从源码结构可以推断，它的核心卖点是把解析、转码、转写等重活放在浏览器本地（或 Worker）完成，转换速度快且无需上传服务端。

三、启动前环境准备：明确这套命令的运行前提

SKILL.md 的 Workflow 第一步默认了环境已经具备或即将完成两件事，理解它们有助于避免“命令报错却不知为何”：

1. 包管理器为 Bun：仓库根 package.json 声明"packageManager": "bun@1.3.3"。所有安装、脚本执行都围绕 Bun 展开（如bun i、bun run build、bun test test）。如果本机 Bun 版本差异过大，建议先按bun@1.3.3对齐。
2. 运行时版本：packages/convert/package.json 的engines声明"node": ">=20.0.0"，开发 Convert 包时应确保 Node.js 不低于 20。
3. Monorepo 工作区：根 package.json 将packages/**全部纳入 npm workspaces（@remotion/convert即位于其中，通过workspace:*协议引用同仓库包，例如@remotion/media、@remotion/whisper-webgpu）。这意味着“安装依赖”必须在仓库根执行一次，才能解析所有 workspace 包。

注意：本仓库为只读用途。上述命令只用于“查看、安装、运行、配置”的本地演示场景，请勿以修改仓库文件为目的执行。

四、逐步实操：按技能文档启动 Convert 本地服务

下面完整复现 SKILL.md 的 5 步工作流，并对每一步补充执行细节与故障排查要点。

步骤 1：在仓库根目录安装依赖并预编译工作区

bun i && bun run build

bun i依据根bun.lock与workspaces配置一次性安装全部 workspace 的依赖。

bun run build对应根 package.json 中的"build": "turbo run make --no-update-notifier"，即通过 Turborepo 触发各包make任务。这一步并非可有可无：@remotion/convert在 dev 模式下会依赖同仓库的@remotion/media、@remotion/design、@remotion/media-parser、@remotion/webcodecs、@remotion/whisper-webgpu等包，这些包需要先生成各自的构建产物（dist / 原生绑定等），Convert 的 Vite dev server 才能正常解析workspace:*导入。首次执行时bun i可能耗时较长（monorepo 依赖树很大），bun run build也会按拓扑顺序编译多个包，请耐心等待其完成、退出码为 0。

步骤 2：在 Convert 包目录内启动开发服务器

cd packages/convert && bun run dev

bun run dev解析到 packages/convert/package.json 中的"dev": "remix vite:dev"——即通过 Remix 的 Vite 插件启动开发服务器，而不是直接vite。

这里存在一个容易踩的细节：技能文档假定你已经身处仓库根目录，因此先cd packages/convert再执行。若直接在工作区根运行会因缺少dev脚本而失败。

步骤 3：保持进程运行并读取终端输出的 URL

SKILL.md 明确要求：“Keep the server process running and read its output for the local URL.” 也就是说，不要让 dev server 在后台被回收或中断——Convert 的入口 HTML、HMR 与路由都依赖这个常驻进程。

预期默认端口为http://localhost:5173（这是 Vite 的默认端口）。如果 5173 被占用，Vite 会自动递增选择下一个可用端口并在终端打印最终地址，因此请“follow the printed URL if Vite chooses another port”，不要盲目假设端口。

步骤 4：在浏览器中打开本地 URL 并完成验证

打开后，依据 packages/convert/app/root.tsx，应用会以Remotion Convert作为文档标题、bg-slate-50作为页面底色渲染，并加载 manifest 与 favicon。此时可以：

• 在首页验证各工具入口（Trim / Crop / Rotate / Mirror / Resize / Transcribe / Probe 等路由）是否可访问；
• 任选一条路由（如trim）拖入一个本地媒体文件，确认 HLS/播放器与转换 UI 能正常初始化。

若你是在 Agent 环境中执行，SKILL.md 提示：如果当前会话还没有可用的浏览器控制工具，应先通过tool_search找到“in-app browser control”类工具，再用它导航到本地 URL。

步骤 5：向用户汇报结果

技能流程的最后一步要求区分两种状态并明确告知：这是一个“全新启动”的服务，还是“已经运行中”的服务（例如端口已被占用时可能命中先前实例）。同时把确切的 Convert URL 交付给用户，方便其直接访问。

五、Dev 脚本背后的构建配置：remix vite:dev在做什么

为什么bun run dev能起效、产物如何组织？答案在 Convert 包的两份 Vite 配置中。

主配置vite.config.ts

packages/convert/vite.config.ts 是 dev 与 SSR 构建共用的入口，核心要点包括：

• 使用@remix-run/dev导出的vitePlugin（Remix Vite 插件），并挂载vercelPreset()——说明该应用线上以 Vercel 为部署目标；
• 启用一组 Remix v3 未来特性开关（v3_singleFetch、v3_lazyRouteDiscovery、v3_fetcherPersist等），保持向 Remix 2.17 的演进兼容；
• 接入vite-tsconfig-paths，使tsconfig.json中定义的~/*、@/*路径别名在 Vite 中生效；
• 额外配置resolve.alias：'@'→./app，与 tsconfig 的paths保持一致；
• 顶部调用installGlobals()，为服务端运行时补齐 fetch 等全局对象。

因此当 SKILL.md 告诉你cd packages/convert && bun run dev时，实际启动的是一个“带 Remix 路由约定、Tailwind 样式、路径别名与 Vercel preset”的 Vite dev server，路由文件即 packages/convert/app/routes 下所见的那批*.tsx。

SPA 产物配置vite-spa.config.ts

值得顺带了解的是，Convert 除了普通页面构建，还支持纯静态 SPA 产物：packages/convert/vite-spa.config.ts 在 Remix 插件中设置ssr: false、buildDirectory: 'spa-dist'，并把base设为/convert/；对应 package.json 中的"build-spa": "remix vite:build -c vite-spa.config.ts && bun build-service-worker.ts"，构建完成后还会调用bun build-service-worker.ts生成 Service Worker。结合根布局中引用的manifest.json（见 packages/convert/app/root.tsx），可以推断该应用支持以 PWA/Service Worker 形式离线缓存静态资源。

六、深入验证与二次开发：可用脚本与源码地图

如果你不只满足于“跑起来”，以下是继续深入时可利用的既有设施（全部来自仓库真实文件）：

• 类型检查：bun run typecheck（即tsc）。注意 packages/convert/tsconfig.json 设置了noEmit: true——Vite 负责产出，tsc 只做类型把关。
• 单元测试：bun run test执行bun test test，测试目录位于 packages/convert/test，运行环境使用@happy-dom/global-registrator（见包内 happydom.ts）。
• 代码规范：bun run lint会先跑tsc，再对app目录执行 ESLint。
• 源码入口：UI 根组件见 packages/convert/app/root.tsx，客户端入口见 packages/convert/app/entry.client.tsx，SEO 描述集中管理在 packages/convert/app/seo.ts。

想要研究转换引擎本身，则应沿工程引用向上追溯：packages/media-parser（媒体容器/流解析）、packages/webcodecs（WebCodecs 封装）、packages/whisper-webgpu（转写能力）三者的源码共同构成 Convert 的“发动机”，而 packages/convert/tsconfig.json 的references正是这三条链路最直接的索引。

七、常见问题速查

总结

convert技能文档虽然短小，但它浓缩的是一条从“仓库就绪”到“浏览器内使用视频转换器”的完整链路：根目录bun i && bun run build负责把 Monorepo 工作区及其底层媒体处理依赖编译就绪；cd packages/convert && bun run dev通过remix vite:dev启动带路由约定的 Vite 开发服务器；随后保持进程常驻、读取打印端口并在浏览器中打开即完成验证。结合 packages/convert 的源码、路由结构与依赖清单，无论是人工复现、Agent 自动化调用（/convert、$convert），还是基于 packages/media-parser、packages/webcodecs、packages/whisper-webgpu 做二次开发，你都能在这份指南中找到准确的落点。

【免费下载链接】remotion🎥 Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion