Remotion API 弃用规范：TypeScript 注解与文档标记的三处同步表示法

Remotion 中“仍可用的公共 API 被弃用”这一状态，通过三处互相呼应的表示来传达：源码中的 JSDoc @deprecated 注解、文档标题的双波浪线删除线，以及紧随标题的 Deprecated 信息提示框。本文完整介绍这套弃用规范（源自仓库内的 SKILL.md），并结合 packages/core、packages/media-utils 的真实源码与 packages/docs 中的实际文档页面，说明如何在添加、审查或讨论一个弃用操作时做到表达一致、可检索、可迁移。

规范的总览：三个位置缺一不可

当一个公共 API（函数、组件、hook、类型、prop、option 或其他形式）被弃用但仍保留可用时，弃用信息需要在三个地方同时体现：

1. 公共 TypeScript API 上的 JSDoc @deprecated 注解——让 IDE 与类型工具向消费者传播弃用信号；
2. 该 API 文档标题的删除线（strikethrough）格式——让读者在文档中一眼识别；
3. 紧跟在该标题之后的、命名为 Deprecated 的 info 提示框（admonition）——说明替代方案。

这三处构成一个完整闭环：IDE 里写代码的人看到第一个，读文档的人看到后两个。规范适用于所有形式的公共 API，无论它是导出函数、React 组件、hook、类型定义，还是某个函数的 prop 或 option。

TypeScript 表示法：JSDoc @deprecated 注解

规范对源码侧的要求是：公共符号上携带 JSDoc @deprecated 注解。注解应当在存在替代方案时说明替代者，并可链接到替代者的文档。SKILL.md 给出的标准形式如下：

/**
 * @deprecated Use `newApi()` instead: https://www.remotion.dev/docs/new-api
 */
export const oldApi = () => {};

仓库中的真实案例

从源码结构看，Remotion 主包中已有大量遵循该模式的注解。以音频时长工具为例，get-audio-duration-in-seconds.ts 中的弃用写法是：

/**
 * @description Gets the duration in seconds of an audio source by creating an invisible `<audio>` tag, loading the audio, and returning the duration.
 * @see [Documentation](https://remotion.dev/docs/get-audio-duration-in-seconds)
 * @deprecated Use Mediabunny instead: https://www.remotion.dev/docs/mediabunny/metadata
 */
export const getAudioDurationInSeconds = (src: string) => {
	return limit(fn, src);
};

/**
 * @deprecated Renamed to `getAudioDurationInSeconds`
 */
export const getAudioDuration = (src: string) => getAudioDurationInSeconds(src);

这里可以看到两类典型弃用语境：

• 被新 API 取代：@deprecated Use Mediabunny instead: ...，注解中直接给出替代方案名称与文档链接；
• 被重命名：@deprecated Renamed to \getAudioDurationInSeconds``，旧名字作为兼容别名保留，指向新名字。

props.ts 展示了 prop 级别的弃用写法，例如 @deprecated \startFrom` was renamed to `trimBefore`；[html5-audio.tsx](https://gitcode.com/GitHub_Trending/re/remotion/blob/16c0012ec5dd6db22b4fdc694d0b658c39bf91f8/packages/core/src/audio/html5-audio.tsx?utm_source=gitcode_repo_files) 中则是对整个组件的重命名弃用：@deprecated This component has been renamed to `Html5Audio`。此外，[Sequence.tsx](https://gitcode.com/GitHub_Trending/re/remotion/blob/16c0012ec5dd6db22b4fdc694d0b658c39bf91f8/packages/core/src/Sequence.tsx?utm_source=gitcode_repo_files) 中对内部使用的字段批量标注 @deprecated For internal use only`，说明该注解也用于表达“不鼓励外部依赖”的边界约束。

注解应放在消费者能接收到的位置

规范中一条容易被忽略的细节是：注解属于“消费者收到它的地方”。对于一个 re-export 或兼容别名，@deprecated 应加在导出的符号上，而不是那个尚未弃用的底层实现上。上面的 getAudioDuration 就是一个典型：它是转发给 getAudioDurationInSeconds 的兼容别名，注解加在别名导出本身，保证 IDE 在旧导入路径上给出弃用提示，而实现体保持干净。

文档表示法：删除线标题 + Deprecated 提示框

文档侧的表示分为三个要素，逐一说明如下。

1. 标题使用双波浪线删除线

被弃用 API 的名称在文档标题中用双波浪线 ~~...~~ 包裹成删除线。注意 <AvailableFrom> 标记必须留在删除线之外，因为它表示该 API 可用的起始版本，与是否弃用是两个独立维度：

# ~~oldApi()~~<AvailableFrom v="4.0.0" />

对于 prop 或 option 级别的弃用，删除线作用于小节标题（H3）：

### ~~`oldOption?`~~

仓库中大量文档遵循了这一格式。例如 get-audio-duration-in-seconds.mdx 的标题为 # ~~getAudioDurationInSeconds()~~；CLI 参数页面 render.mdx 中有 ### ~~\--quality`~~这样的写法——删除线包住--quality，` 标记保留在其外。

2. frontmatter 的 title 保持不变

frontmatter 中的 title 字段不随弃用而改动（例如 get-audio-duration-in-seconds.mdx 的 frontmatter 仍写着 title: getAudioDurationInSeconds()）。如果一个页面原本完全依赖 frontmatter title 渲染标题，那么在弃用时必须显式写一个带删除线的标题来覆盖它——这正是上面这些页面显式写出 # ~~...~~ 标题的原因。

3. 标题之后紧跟 Deprecated 信息提示框

一个名为 Deprecated 的 info admonition 紧跟在删除线标题之后，并在存在替代方案时指向替代者。实际页面（get-audio-duration-in-seconds.mdx）中的完整形态如下：

# ~~getAudioDurationInSeconds()~~

:::info Deprecated
This function has been deprecated. Use `getMediaMetadata()` instead, which is faster and supports more formats.
:::

另一个例子来自 deploysite.mdx，deploySite() 的弃用提示框推荐了拆分后的组合（bundle() + deploySiteFromBundle()），并顺带解释了理由（“避免部署时重复构建未变化的 bundle”）。可以看到，提示框不仅是“指向替代品”，还可以给出迁移建议的动机，这比裸链接更有可操作性。

范围边界：哪些不属于本规范

SKILL.md 明确划定了这套规范不覆盖的部分：

• 运行时警告、侧边栏徽章、发布说明、移除版本号、移除时的行为——这些目前都不属于 API 弃用的标准化范围，不应假设仓库对它们有一致的约定；
• 已移除（Removed）的 API 在规范之外——它们可能继续保留文档以便迁移参考，但已经没有可供标注的公共符号，因此不适用 JSDoc @deprecated 部分。

一个佐证：Clipper.tsx 中对已移除组件的标注直接写成“<Clipper> has been removed as of Remotion v4.0.228”，说明移除类说明在措辞上独立于弃用规范。

实操清单：添加或审查一次弃用时核对什么

结合上述规范，一次完整的弃用操作可以按以下清单核对：

核对点	位置	依据
公共符号有 JSDoc @deprecated，说明替代者（如存在）并可附文档链接	源码文件	SKILL.md
别名/re-export 场景下，注解在导出的符号上而非实现体	源码文件	参考 get-audio-duration-in-seconds.ts
文档标题用 ~~...~~ 删除线，<AvailableFrom> 留在删除线外	对应 .mdx	参考 deploysite.mdx
prop/option 的删除线写在 H3 标题上	对应 .mdx	参考 html5-audio.mdx
frontmatter title 保持不变；仅依赖 title 的页面需显式补删除线标题	对应 .mdx	参考 get-audio-duration-in-seconds.mdx
标题后紧跟 :::info Deprecated ... ::: 提示框，指向替代方案	对应 .mdx	参考 get-audio-duration-in-seconds.mdx
不承诺运行时警告、徽章、移除版本等未标准化行为	全部	规范“Scope”一节

这套“源码注解 + 删除线标题 + 弃用提示框”的三处同步约定，使弃用信息在 IDE 补全、文档阅读、页面搜索三个入口上都保持一致，读者无论从哪里进入都能拿到同一条迁移路径。