kinetograph-migrate

将 Remotion 项目迁移到 Kinetograph

Remotion 项目的大部分内容都可以原样运行。CLI 会将 remotion 和 24 个 @remotion/* 包映射到 Kinetograph 的核心，因此视频代码无需更改。需要更改的是周边工具，以及少数没有对应替代项的包。渲染流程中完全没有浏览器。无论出于什么原因，都不要添加浏览器作为临时方案：不要使用 Chrome、Puppeteer、Playwright 或 iframe。

使用 npx kinetograph <command> 运行命令。添加 --json 可获取一个 JSON 对象。其他命令和项目 API，请查阅 kinetograph 技能。

工作流程

1. 找到入口和合成。 查看 package.json（脚本、依赖项）以及任何 remotion.config.ts 文件：doctor 只能看到入口导入的文件，因此播放器页面、渲染脚本或配置文件都不会出现在报告中。在项目中搜索 @remotion/(player|renderer|bundler|lambda|cloudrun|cli|three)、from 'three' 和 IFrame，并将每个匹配项都视为一个问题。入口是调用 registerRoot 的文件（通常是 src/index.ts；package.json 脚本或 remotion.config.ts 会指出它）。运行 kinetograph compositions <entry>。如果它报错提示 ... is not supported by Kinetograph yet，那么该导入就是第一个问题。（消息会提示运行 doctor，但在修复该导入前，doctor 也会因同一导入而停止。）
2. 运行 Doctor。 执行 kinetograph doctor <entry>（针对单个合成时添加 --comp <id>）。它会报告引擎无法绘制的每个元素、属性和原因，并标出帧范围。无法打包的导入会使命令在生成任何报告之前就停止，并指出包名；先修复该问题，然后再次运行 doctor。保留报告，并根据报告逐项处理。
3. 修复每个问题。 根据问题类型选择处理方式：
   • @remotion/three 或 three 导入：阅读 references/three.md。
   • @remotion/player、@remotion/renderer、@remotion/bundler、@remotion/lambda、@remotion/cloudrun、@remotion/cli、remotion.config.ts、npm run 脚本、webpack 覆盖配置：阅读 references/tooling.md。
   • 报告中的 IFrame、@remotion/webcodecs、@remotion/media-parser 示例回调、@remotion/rive、@remotion/skia、Canvas、WebGL 或 CSS 问题：阅读 references/unsupported.md。
   • 其他问题：报告中会指出相应属性或元素。将其改为引擎支持绘制的内容，或将其移除。不要猜测；再次运行 doctor。
4. Lint。 运行 kinetograph lint <entry> 和 kinetograph check <entry>（检查类型错误）。修复所有错误。如果错误提示 react 缺少声明文件，说明尚未安装 @types/react：请将其作为开发依赖添加，并使用与项目 React 版本相同的版本，然后告知用户。这不是迁移问题，也不会阻止 render。
5. 查看效果。 运行 kinetograph strip <entry> -n 12 -o out/strip.png，然后打开 PNG。单帧预览可使用 still <entry> <frame>。将效果与项目原本的预期进行比较（Remotion 渲染结果、屏幕截图或用户描述；如果没有可供比较的内容，就根据代码检查并说明无法进行比较）。即使 doctor 和 lint 都没有问题，文本仍可能缺失，因此要检查屏幕上是否显示了每个标题和说明文字（参见“字体”）。
6. 渲染。 运行 kinetograph render <entry> --comp <id> -o out/video.mp4 --strict（可先使用 --range 0..30 快速测试；a..b 在 b-1 帧停止，a..=b 则包含 b 帧）。如果任何帧包含不受支持的内容，--strict 就会在第一帧报错，因此不会生成缺少内容的视频。

如果修复后 --strict 仍然失败，说明确实还有未处理的问题。可以对其进行近似处理（说明处理方式）或移除，然后在第 7 步中说明。最终渲染时，不要通过去掉 --strict 来掩盖问题。

7. 向用户汇报。 列出哪些内容已原样移植、哪些内容被替换（以及替换成什么）、哪些内容被移除或近似处理，并提供现在运行项目所需的命令。若结果与 Remotion 不同，请明确说明。

规则

• remotion 导入无需修改。不要将 remotion 或 @remotion/* 导入改写为 @kinetographdev/core。
• 绝不要悄悄移除功能。任何省略或近似处理都要写入第 7 步的报告。
• 字体。 未注册字体中的文本可能完全无法绘制，且 doctor 不会发出警告。通常是因为 fontFamily 只指定了系统字体（Helvetica, Arial, sans-serif）。请注册用户有权使用的字体文件：使用 @remotion/google-fonts/<Family>（loadFont()）、来自 @kinetographdev/core 的 registerFont({ family, path: staticFile('F.ttf') })，或在导入的 .css 文件中使用 @font-face { src: url(...) }。不要将系统字体复制到项目中。
• 渲染是帧的纯函数。将 Date.now()、Math.random() 和计时器替换为帧计算和 random(seed)。
• 无网络连接。fetch 只能读取项目文件。将远程资源复制到 public/，并使用 staticFile。
• 不要为渲染路径添加依赖，唯一例外是作为开发依赖的 kinetograph（它会引入 3D 元素所用的 @kinetographdev/core）。如果它尚未发布到 npm，请询问用户应从哪里安装。工作室或测试所需的包可以添加。

覆盖范围一览

已映射 Core remotion 和以下 @remotion/* 包：transitions、motion-blur、noise、paths、shapes、layout-utils、animation-utils、captions、google-fonts、fonts、lottie、gif、media-utils、media、light-leaks、starburst、sfx、zod-types、timeline-utils、media-parser、webcodecs、canvas、rive、skia。有意不移植：three、player、renderer、bundler、cli、lambda、cloudrun、tailwind、tailwind-v4（Tailwind 本身可用）。完整表格见文档站 /docs/guides/migrate/。GSAP（核心、免费插件、Flip）也可用：在布局 effect 中将暂停的时间线定位到 frame / fps，或者让 useEffect 中的 gsap.to 自行播放（/docs/compat/#gsap）。

无需改写：.svg 文件的 <Img src>（其中的文本会被省略）、命名颜色和函数式 CSS 颜色（white、rgb()、oklch()）、Fragment 中的 <TransitionSeries> 和 <Series> 子元素、<canvas> 和 <Canvas>、-webkit-text-stroke，以及字体缺少的符号或表情符号（会使用捆绑的备用字体；CJK 字符需要加载字体）。库（Recharts、d3、rough.js、Chart.js、anime.js、Motion、Paper.js）只要根据帧绘制，就能原样运行；请参阅 /docs/libraries/。Mermaid 使用默认 HTML 标签（<foreignObject>）绘制；请先加载标签字体。