如何在TypeScript中正确定义MediaRecorder视频码率模式类型？

MediaRecorder API 为浏览器端音视频录制提供了基础能力，其中 bitrateMode 属性用来控制视频编码器采用恒定码率（CBR）还是可变码率（VBR）策略。在 TypeScript 项目中，直接使用标准 DOM 类型时可能会发现 MediaRecorderOptions 并未声明 bitrateMode 字段，或者该字段被宽松地定义为 string，导致无法在编译阶段拦截无效值。要解决这个问题，需要理解码率模式的底层逻辑，然后通过声明合并或自定义类型为项目补全类型定义。本文会详细说明具体做法，并给出可在实际项目中直接使用的代码示例。

MediaRecorder 码率模式的工作机制

VideoBitrateMode 是 MediaRecorder API 中控制视频编码策略的关键选项。在 VBR（Variable Bitrate）模式下，编码器会根据画面复杂度动态调整每一段时间内的码率：静态场景分配较少的码率，高速运动或复杂纹理画面分配更多码率。这样可以在整体平均码率接近目标值的同时保持画质稳定，但输出文件的大小无法提前准确预估。VBR 适合本地录制、后期剪辑等对文件体积不敏感但重视画质的场景。

与 VBR 相对的是 CBR（Constant Bitrate）模式，编码器会尽量让每秒输出的比特数保持恒定。CBR 的优势在于文件大小可以预测，适合直播、实时通信或固定带宽传输场景。不过，当画面复杂度突然升高时，固定码率可能导致量化参数变差，出现块效应或细节丢失。因此，选择哪种模式需要根据实际业务权衡。

MediaRecorderOptions 中的 bitrateMode 属性只接受两个字符串值："vbr" 和 "cbr"。虽然标准已经定义，但不同浏览器对 VP8、VP9、H.264 等编码器的支持程度并不一致。例如 Firefox 对 WebM 容器中的 VP8 编码器支持 CBR，而 Chrome 在某些版本中对 VP9 的 CBR 支持不完整。所以在使用前最好通过 MediaRecorder.isTypeSupported 检测目标 MIME 类型是否可用。下面是一段不涉及 TypeScript 类型约束的原生 JavaScript 用法，方便理解 API 本身的行为。

const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
const options = {
  mimeType: 'video/webm;codecs=vp9',
  videoBitsPerSecond: 2500000,
  bitrateMode: 'vbr'
};
const recorder = new MediaRecorder(stream, options);

TypeScript 标准类型缺失与声明合并

TypeScript 不同版本的 lib.dom.d.ts 对 MediaRecorderOptions 的定义存在差异。许多项目仍在使用 TypeScript 4.x 或者较旧的 @types/dom，其中 MediaRecorderOptions 仅有 mimeType、videoBitsPerSecond、audioBitsPerSecond 等字段，bitrateMode 并未出现。如果直接写 bitrateMode: 'vbr'，会触发对象字面量类型检查错误，因为该属性在接口中不存在。一些开发者采用 as any 或者类型断言绕过，但这会让整个 options 对象失去类型保护，后续维护时容易引入拼写错误。

更优雅的做法是利用 TypeScript 的声明合并（declaration merging）能力。接口可以跨文件合并，只要在全局作用域中对已存在的 interface 进行补充声明，就能为 MediaRecorderOptions 追加 bitrateMode 字段。这种方式不需要修改 node_modules 中的类型定义，也不会影响项目其他部分的编译。声明合并后的类型会在所有文件中自动生效，团队成员无需额外导入。

声明合并有两种书写方式。如果声明文件是全局脚本（即没有 import 或 export 语句），可以直接写出 type 别名和 interface 补充。如果声明文件是模块（含有 import 或 export），则需要使用 declare global 包裹。下面分别展示两种写法。

// types/media-recorder.d.ts
type VideoBitrateMode = 'vbr' | 'cbr';

interface MediaRecorderOptions {
  bitrateMode?: VideoBitrateMode;
}

// types/media-recorder.d.ts
export {};

declare global {
  type VideoBitrateMode = 'vbr' | 'cbr';

  interface MediaRecorderOptions {
    bitrateMode?: VideoBitrateMode;
  }
}

第一种方式适合纯类型声明文件，第二种方式适合与其他 import/export 共存的情况。无论哪种方式，最终效果都是让 MediaRecorderOptions 获得 bitrateMode?: VideoBitrateMode 这个可选属性。

在实际项目中使用补全后的类型

完成声明合并后，业务代码中就可以直接使用 MediaRecorderOptions 的 bitrateMode 字段，并获得完整的类型检查。初始化 MediaRecorder 时，既可以传入 'vbr' 也可以传入 'cbr'，但如果写错字符串，TypeScript 会立即提示类型错误。下面是一段完整的初始化示例，包含获取媒体流、选择编码器以及创建录制器。

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const options: MediaRecorderOptions = {
  mimeType: 'video/webm;codecs=vp9',
  videoBitsPerSecond: 2000000,
  bitrateMode: 'vbr'
};
const recorder = new MediaRecorder(stream, options);

// 下面的写法会报错：
// const wrongOptions: MediaRecorderOptions = {
//   mimeType: 'video/webm;codecs=vp9',
//   bitrateMode: 'constant'
// };

如果项目需要更严格的约束，还可以单独导出一个 VideoBitrateMode 类型，供其他模块使用。例如在封装录制函数的文件中，用 type 别名定义参数类型，避免散落的字符串字面量。声明合并保证了全局接口的增强，而独立的类型别名则便于复用和文档化。

另外，videoBitsPerSecond 与 bitrateMode 有紧密关系。在 VBR 模式下，videoBitsPerSecond 表示目标平均码率；在 CBR 模式下，它表示近似恒定码率。实际选择参数时，可以参考下表进行权衡。

浏览器兼容性与回退处理

尽管标准已经支持 bitrateMode，但不同浏览器的实现进度并不一致。某些移动端浏览器对 WebM 容器支持有限，通常只会选择 MP4 容器和 H.264 编码器，而 H.264 的 VBR/CBR 支持取决于操作系统硬件编码器。如果盲目设置 bitrateMode，可能被浏览器静默忽略，甚至导致 MediaRecorder 创建失败。因此需要在运行时做一定的环境检测和容错处理。

一种常见的防御式写法是：先通过 MediaRecorder.isTypeSupported 选择当前浏览器可用的 MIME 类型，再根据该类型决定是否传入 bitrateMode。如果目标类型不确定，可以将 bitrateMode 放到条件分支中，或者用 try-catch 捕获异常并回退到默认配置。下面的代码展示了这个思路。

function createRecorder(stream: MediaStream): MediaRecorder {
  const mimeType = MediaRecorder.isTypeSupported('video/webm;codecs=vp9')
    ? 'video/webm;codecs=vp9'
    : MediaRecorder.isTypeSupported('video/webm')
      ? 'video/webm'
      : 'video/mp4';

  const options: MediaRecorderOptions = {
    mimeType,
    videoBitsPerSecond: 2000000
  };

  // 只有 WebM 容器下的 VP8/VP9 才尝试设置码率模式
  if (mimeType.startsWith('video/webm')) {
    options.bitrateMode = 'vbr';
  }

  try {
    return new MediaRecorder(stream, options);
  } catch (err) {
    // 回退到默认配置
    return new MediaRecorder(stream);
  }
}

把创建逻辑封装成统一函数，可以集中处理类型检查、编码器检测和异常回退。这样业务侧只需要调用 createRecorder(stream)，不必关心底层兼容性细节。配合前面完成的全局类型声明，整个项目在编译期和运行期都有更好的保障。

总结来说，TypeScript 中定义 MediaRecorder 的视频码率模式类型并不复杂，核心在于理解标准库的缺失，并用声明合并补全 MediaRecorderOptions。将类型别名、运行时检测和统一封装结合使用，可以让 MediaRecorder 录制功能既类型安全又具备良好的浏览器兼容性。

TypeScriptMediaRecorder视频码率模式修改时间：2026-09-29 14:02:19