TypeScript的标准库对MediaRecorder API的类型定义已经相当完善，但它无法覆盖所有浏览器实现中的非标准扩展属性。以视频帧率为例，部分Chromium内核浏览器为MediaRecorderOptions对象支持一个名为videoFrameRate的属性，用于为录制的视频流指定目标帧率。然而在最新版TypeScript自带的lib.dom.d.ts中，MediaRecorderOptions接口并不包含videoFrameRate字段。这意味着如果你直接给MediaRecorder构造函数传入带有videoFrameRate的配置对象，编译器会报错提示对象字面量只能指定已知属性。很多开发者因此选择as any规避检查，但这样会破坏类型安全，后续重构时也容易引入隐性bug。

要解决这个问题，最规范的方式是利用TypeScript的声明合并机制。接口是开放的，我们可以在自己的类型声明文件中重新声明MediaRecorderOptions接口，并为其补充videoFrameRate属性。这样既不需要改动官方类型库，也能让编辑器智能提示和类型检查正常工作。下面先看一段有问题的代码，它能直观展示类型缺失带来的困扰。

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const options: MediaRecorderOptions = {
  mimeType: 'video/webm;codecs=vp9',
  videoBitsPerSecond: 2_500_000,
  videoFrameRate: 30 // 这里会报错：对象字面量只能指定已知属性
};
const recorder = new MediaRecorder(stream, options);

编译时TypeScript会因为videoFrameRate不属于MediaRecorderOptions而抛出TS2353错误。常见的工作区方案是用类型断言强行绕过，比如将options断言为MediaRecorderOptions & { videoFrameRate?: number }，但这样每次使用都需要重复断言，而且无法获得全局的类型提示。另一种做法是直接在业务代码中修改全局interface，但如果你在多个文件中分散定义，容易造成声明冲突或覆盖不完整。因此，集中在一个.d.ts文件中进行类型扩展是最推荐的方式。

利用声明合并扩展MediaRecorderOptions

TypeScript的接口声明合并允许我们在不修改原始定义的情况下为已有接口新增成员。具体做法是创建一个全局的.d.ts文件，比如media-recorder-ext.d.ts，然后在其中声明与lib.dom.d.ts中同名的MediaRecorderOptions接口。注意，必须将该文件包含在tsconfig.json的include配置范围内，否则编译器不会加载它。接口声明合并后，videoFrameRate会作为可选属性出现在MediaRecorderOptions上。

// media-recorder-ext.d.ts
interface MediaRecorderOptions {
  videoFrameRate?: number;
}

这个扩展只对新代码生效，已经存在的代码如果已经使用as any或断言，不会受到影响。videoFrameRate被定义为number类型，但为了更精确，可以考虑使用联合类型，例如允许常见的帧率值如24、30、60，甚至支持分数帧率。但在标准尚不稳定时，number已经足够灵活。如果你希望进行更严格的字面量限制，可以定义一个类型别名，然后在接口中使用该别名。

同时需要注意到，videoFrameRate并非W3C标准，不同浏览器的支持情况差异很大。在生产环境中，除了类型定义，还需要加上运行时能力检测。你可以使用MediaRecorder的静态方法isTypeSupported或直接判断对象属性是否存在，但这属于运行时代码，与TypeScript类型扩展并不冲突。例如可以在创建MediaRecorder之前检查videoFrameRate是否被支持，如果不支持则回退到不传该属性。

自定义帧率类型的更多细节

除了直接扩展全局接口，你也可以定义一个独立的配置类型，然后通过类型断言或者工厂函数来规范使用。这种方式的好处是避免全局命名空间污染，适合大型项目或多模块协作。例如创建一个VideoRecorderOptions类型，它继承MediaRecorderOptions并添加videoFrameRate字段。然后编写一个createVideoRecorder函数，接收VideoRecorderOptions参数，内部处理类型断言和兼容性逻辑。

type VideoRecorderOptions = MediaRecorderOptions & {
  videoFrameRate?: number;
};
function createVideoRecorder(stream: MediaStream, options: VideoRecorderOptions) {
  // 在这里可以做运行时检查，如果不支持则删除videoFrameRate
  const finalOptions: MediaRecorderOptions = { ...options };
  if (!('videoFrameRate' in finalOptions)) {
    delete finalOptions.videoFrameRate;
  }
  return new MediaRecorder(stream, finalOptions);
}

上面的例子中，VideoRecorderOptions是交叉类型，继承了所有MediaRecorderOptions属性并额外加入videoFrameRate。工厂函数接收这个类型，然后根据运行时支持情况决定是否保留该属性。删除属性后的finalOptions符合标准MediaRecorderOptions类型，从而避免了直接构造时的类型错误。这种方式不需要全局声明合并，对局部代码更加友好，同时也便于集中处理兼容逻辑。

如果项目已经采用了全局扩展，仍然可以使用类似工厂函数的方式来封装运行时检查。实际上，将类型扩展和运行时能力检测分离是更健壮的架构。类型扩展解决编译期问题，运行时检测解决浏览器兼容性问题，二者相辅相成。

编写完整的类型定义与编译验证

为了更好地维护类型扩展，建议将videoFrameRate定义得更具描述性，比如添加JSDoc注释说明哪些浏览器支持该属性。这有助于团队其他成员理解该非标准属性的来源和风险。完整的.d.ts文件可以这样写：

// media-recorder-ext.d.ts
interface MediaRecorderOptions {
  /**
   * 目标视频帧率，部分基于Chromium的浏览器支持。
   * 例如：30、60。如果浏览器不支持，该属性会被忽略。
   */
  videoFrameRate?: number;
}

保存该文件后，重启编辑器或重新编译项目，之前报错的代码就会通过类型检查。智能提示也会在输入videoFrameRate时自动补全。为了验证类型扩展确实生效，你可以编写一个简单的测试文件，显式声明一个MediaRecorderOptions变量并设置videoFrameRate，然后执行tsc --noEmit检查，应当不再出现TS2353错误。如果仍然报错，需要检查该.d.ts文件是否被tsconfig包含，以及文件是否带有顶层export或import关键字导致其被视为模块而非全局声明。

另一个细节是，如果你的项目使用ES模块，全局扩展的文件中不能出现任何export或import语句。一旦包含这些语句，该文件就会被视为模块，其中声明的接口只在模块内部可见，不会合并到全局的MediaRecorderOptions。如果需要同时使用模块和全局扩展，可以创建一个单独的全局.d.ts文件，专门用于全局接口扩展，该文件保持无导出导入状态。

最后需要强调，虽然videoFrameRate类型扩展解决了编译问题，但运行时是否真正生效取决于浏览器实现。在Firefox或Safari中，该属性可能被忽略。因此，在实际项目中，建议将类型扩展与能力检测结合使用，并在录制结果上验证帧率是否达到预期。如果浏览器不支持指定帧率，可以考虑通过调整MediaStreamTrack的frameRate约束来实现近似效果，但这涉及不同的API，本文不做展开。

总结来说，TypeScript中的接口声明合并为我们提供了一个安全、优雅的方式来扩展不完整的标准类型定义。通过一个简单的全局.d.ts文件或者局部交叉类型，即可为MediaRecorderOptions添加视频帧率支持，同时保持代码的类型安全和可维护性。