v5-breaking-changes

Remotion 5 破坏性变更

使用中央编译时标志 packages/core/src/v5-flag.ts：

export const ENABLE_V5_BREAKING_CHANGES = false as const;

保留编译时标志

• 在 v4/main 发布线上，将标志保留为字面量 false as const。
• 不要将其改成环境变量、运行时选项或通用的 boolean。它的字面量类型既决定了公开的 TypeScript API，也决定了运行时行为。
• 不要引入另一个 v5 标志。
• 在 packages/core 中，从 v5-flag.ts 导入标志。从其他包中，使用 NoReactInternals.ENABLE_V5_BREAKING_CHANGES（来自 remotion/no-react），确保所有包使用相同的值。

切出 v5 发布线时，只需将这一个常量改为 true as const，即可同时启用 v5 运行时行为和公开的 TypeScript API。

控制运行时行为

基于中央标志分支选择默认值和行为，同时保留现有的 v4 路径：

const effectiveValue =
	value ??
	(NoReactInternals.ENABLE_V5_BREAKING_CHANGES ? v5Default : v4Default);

除非 v5 API 有意移除用户提供的值，否则显式的用户值应继续优先。运行时验证应与所选的公开类型保持一致，以便 JavaScript 调用方和绕过 TypeScript 的调用方也能获得 v5 行为。

控制公开类型

对于破坏性的签名或选项变更，使用基于字面量标志的条件类型，选择完整的不兼容部分：

type VersionedOptions =
	typeof NoReactInternals.ENABLE_V5_BREAKING_CHANGES extends true
		? V5Options
		: V4Options;

v4 分支必须公开兼容的 API。v5 分支必须只公开预期的 v5 API；不要将已移除的字段保留为可选字段，也不要将两个版本合并成一个联合类型。

可参考以下现有实现：

• packages/renderer/src/v5-required-input-props.ts：v5 中的必需选项。
• packages/renderer/src/open-browser.ts：从公开类型中移除选项，同时保留 v4 兼容性。
• packages/google-fonts/src/base.ts：将条件公开类型与运行时强制校验配对使用。

记录每一项面向用户的破坏性变更

在 packages/docs/docs/5-0-migration.mdx 中添加或更新相应条目。说明：

• v5 中发生了什么变化；
• v4 的行为或签名；
• 用户应如何迁移；
• 在适用时提供替代代码或选项。

验证变更

完成前，请检查：

1. 标志保持为 false as const 时，v4 运行时行为和公开类型仍然兼容。
2. 只将中央标志改为 true as const 时，会同时选择 v5 运行时路径和 v5 公开类型。
3. 运行时验证与条件 TypeScript API 一致。
4. 迁移指南包含面向用户的变更说明。
5. 所有受影响的包都通过针对性构建、现有测试、lint 和格式检查。

不要为了测试 v5 而提交切换后的标志。在共享的 v4/main 线上，将其恢复为 false as const。

v5 不再与 v4 共用实现后，可以移除兼容性分支。

来源：Remotion 5.0 masterplan implementation mechanism。