Remotion Mediabunny 升级标准流程：upgrade-mediabunny 技能与 Monorepo 版本一致性机制

本篇技术指南基于 Remotion 仓库中 upgrade-mediabunny 技能文档，讲解如何在 Remotion monorepo 中将 Mediabunny 及其 @mediabunny/* 子包升级到最新版本。读完本文，你将掌握完整的升级步骤、每个版本声明点的源码位置，以及这些版本号在 npx remotion add、npx remotion upgrade、npx remotion versions 中的具体作用机制。

Mediabunny 在 Remotion 中的角色与影响面

Mediabunny 是 Remotion 的第三方多媒体处理库（编解码、音频/视频格式支持），官方文档 version.mdx 明确说明 @remotion/media 与 @remotion/media-utils 两个包直接使用它。值得注意的是：从 Remotion 4.0.355 起，Mediabunny 不再被打包进 Remotion 产物，而是从用户项目的 node_modules 中加载（version.mdx 的 History 小节）。这意味着 Remotion 每次发版必须精确锁定一个 Mediabunny 版本，否则用户装到的多媒体能力可能与 Remotion 实际测试过的不一致——这正是仓库需要一套机械化升级流程的根本原因。

哪些包引用了 Mediabunny

在仓库中搜索 mediabunny 依赖声明，可以确认当前的引用分布分两种模式：

模式一：catalog: 间接版本（主仓库内部包）。以根 package.json 中的 workspaces.catalog 为单一事实来源，以下包均声明 "mediabunny": "catalog:" 或对应的 @mediabunny/* 条目，版本由 catalog 统一决定：

包	引用的 Mediabunny 依赖
packages/media	mediabunny
packages/media-parser	mediabunny
packages/media-utils	mediabunny
packages/convert	mediabunny 及 mp3/aac/flac/prores/ac3/dts 编码器全家
packages/timeline-utils	mediabunny、@mediabunny/server
packages/brand、packages/example、packages/studio、packages/docs、packages/promo-pages、packages/canvas-capture-extension、packages/jonnys-videos	视场景引用 mediabunny 与部分 @mediabunny/*

模式二：显式版本号（template-* 模板）。模板包发布给外部用户，不能依赖 monorepo 的 catalog，因此写死版本号。当前快照中持有显式版本的模板包括：

• packages/template-recorder/package.json："mediabunny": "1.55.5"
• packages/template-three/package.json："mediabunny": "1.55.5"
• packages/template-music-visualization/package.json："mediabunny": "1.55.5"

这就是技能文档特别强调「Templates use explicit versions, not catalog:, so update them manually」的原因：升级 catalog 不会自动带动模板，必须逐个手工同步，否则模板用户装到的 Mediabunny 版本会落后于 Remotion 主包，从源码结构看可能引入编解码行为差异。

升级六步走：完整操作手册

以下步骤完整继承自 SKILL.md，并结合当前仓库快照（Mediabunny 版本为 1.55.5）补充了每步的实际操作对象。

第一步：查询最新 Mediabunny 版本

npm view mediabunny version

以该输出作为本次升级的目标版本号（下文中记为 X.Y.Z）。

第二步：更新根 package.json 的 catalog 版本

技能文档要求更新 mediabunny、@mediabunny/mp3-encoder 和 @mediabunny/ac3 三项。实际上 package.json 的 catalog 段共登记了 8 个 Mediabunny 系条目，当前全部为 1.55.5：

"mediabunny": "1.55.5",
"@mediabunny/server": "1.55.5",
"@mediabunny/mp3-encoder": "1.55.5",
"@mediabunny/aac-encoder": "1.55.5",
"@mediabunny/flac-encoder": "1.55.5",
"@mediabunny/prores": "1.55.5",
"@mediabunny/ac3": "1.55.5",
"@mediabunny/dts": "1.55.5"

升级时应把这 8 项全部对齐到 X.Y.Z（它们始终同版本发布），确保所有 catalog: 消费者拿到同一套编解码能力。

第三步：手工同步 template-*/package.json 的显式版本号

遍历 packages/template-*/package.json，将其中 mediabunny 及任意 @mediabunny/* 依赖改为 X.Y.Z。当前快照中需要检查的至少包括 template-recorder、template-three 与 template-music-visualization。

第四步：更新 packages/cli/src/extra-packages.ts

extra-packages.ts 导出一份 EXTRA_PACKAGES 版本映射表，当前内容覆盖了 Mediabunny 全家加上 zod：

export const EXTRA_PACKAGES: Record<string, string> = {
	mediabunny: '1.55.5',
	'@mediabunny/ac3': '1.55.5',
	'@mediabunny/dts': '1.55.5',
	'@mediabunny/mp3-encoder': '1.55.5',
	'@mediabunny/aac-encoder': '1.55.5',
	'@mediabunny/flac-encoder': '1.55.5',
	'@mediabunny/prores': '1.55.5',
	zod: '4.4.3',
};

该表是 Remotion CLI 面向用户安装/升级 Mediabunny 时的版本锚点（下一节详述），升级时必须同步改成 X.Y.Z。

第五步：更新 packages/studio-shared/src/package-info.ts

package-info.ts 中的 extraPackages 数组向 Studio 提供可安装的「额外包」元数据，当前包含 mediabunny、@mediabunny/ac3、@mediabunny/dts、@mediabunny/prores 四条记录（各带 version、description、docsUrl 字段）。将其中 version: '1.55.5' 改为 X.Y.Z。从源码结构看，该列表与 extra-packages.ts 不完全一一对应（这里未列出 mp3/aac/flac 编码器），说明它是面向 Studio UI 的子集展示，升级时按各自现存的条目修改即可。

第六步：更新文档兼容表 version.mdx

version.mdx 维护一张「Remotion 版本 ↔ Mediabunny 版本」兼容表，当前顶部两行为：

Remotion Version	Mediabunny Version
4.0.520	1.55.5
4.0.513	1.55.1

技能文档规定：本次升级所对应的 Remotion 版本 = 根 package.json 中记录版本的 patch 位加 1，然后把新行插入表头。例如 Remotion 当前为 4.0.520（可从 packages/core/package.json 的 "version": "4.0.520" 交叉印证，两者当前一致），若本次把 Mediabunny 升到 1.56.0，则新增一行 4.0.521 | 1.56.0。当前仓库快照中根 package.json 的顶层 version 字段为 0.0.0（monorepo 根包占位值），而 Remotion 核心包版本在 packages/core/package.json 中为 4.0.520，实际操作时以此为核心包版本做 patch 递增即可。

第七步：重新安装依赖

bun i

在仓库根目录执行，让 lockfile（bun.lock）与各工作区的 node_modules 解析到新版本。

版本号为什么必须同步：CLI 的三个消费点

EXTRA_PACKAGES 与 extraPackages 不只是「记录」，它们直接驱动三个面向用户端子的命令，这也是升级必须精确到具体 patch 版本的原因：

1. npx remotion add mediabunny：add.ts 中，若目标包在 EXTRA_PACKAGES 中，安装命令直接拼为 ${pkg}@${EXTRA_PACKAGES[pkg]}，即硬编码锚定版本，保证用户装到的 Mediabunny 与 Remotion 当前版本配对。version.mdx 中推荐的安装命令正是依赖这一机制。
2. npx remotion upgrade：upgrade.ts 以 {...EXTRA_PACKAGES} 为默认目标版本集合；运行时会尝试拉取各包的线上版本，拉取失败则回退到 EXTRA_PACKAGES 中的默认值（第 46 行注释明确说明了该兜底路径），最终在第 96 行按 extraPackageVersions[pkg] ?? EXTRA_PACKAGES[pkg] ?? targetVersion 决定写入用户 package.json 的版本。因此仓库里的 extra-packages.ts 就是「用户执行 upgrade 时 Mediabunny 升到哪个版本」的源头。
3. npx remotion versions：versions.ts 遍历 Object.entries(EXTRA_PACKAGES)，把用户实际安装的 Mediabunny 版本与期望版本逐一比对；version.mdx 建议用该命令校验版本是否正确，而校验输出中的文档跳转链接则来自 extra-packages.ts 的 EXTRA_PACKAGES_DOCS 映射。

换言之，第四步、第五步改动的是「Remotion 告诉外部世界该用哪个 Mediabunny」，第二、三步改动的是「Remotion 自身构建与模板用的是哪个版本」，第六步则是把配对关系公开成文档——三者缺任何一环，npx remotion versions 的校验结论就会失真。

升级完成后的自检清单

检查点	期望结果	依据
根 package.json catalog	8 个 Mediabunny 系条目全部为 X.Y.Z	SKILL.md 第 2 步
所有 packages/template-*/package.json	显式版本均为 X.Y.Z，无遗漏	技能文档第 3 步（模板不使用 catalog:）
extra-packages.ts	7 个 Mediabunny 条目均为 X.Y.Z（zod 不动）	技能文档第 4 步
package-info.ts	extraPackages 中 4 条 Mediabunny 记录的 version 为 X.Y.Z	技能文档第 5 步
version.mdx	表头新增 Remotion(patch+1) | X.Y.Z 一行，且正文「current version」段落同步更新	技能文档第 6 步
bun i	无解析冲突，lockfile 更新	技能文档第 7 步

遵循以上流程后，仓库内部构建、模板项目、用户端 add/upgrade/versions 命令三处的 Mediabunny 版本即重新收敛到同一坐标，这也是 Remotion 能够对外承诺「某 Remotion 版本精确对应某 Mediabunny 版本」这一兼容表可信的前提。