在TypeScript中使用WebRTC媒体采集时，echoCancellation 这个字段看似简单，但在约束建模上很容易被简化成单纯的布尔值。实际上，Media Capture and Streams规范将音频约束统一抽象为 ConstrainBoolean，它不仅允许直接传 true 或 false，还允许传入 exact 和 ideal 参数来表达强度不同的约束语义。对于回声消除这种涉及音频处理链路的约束，只使用 boolean 类型会丢失对理想值、精确值和能力探测结果的表达能力。本文会从约束类型设计、运行时校验和集成调用三个层面，给出一个完整、可落地的 TypeScript 类型方案。

先看清约束语义：boolean 与 ConstrainBoolean 的差异

在标准库的DOM类型中，MediaTrackConstraintSet 是所有媒体轨道约束的集合接口，MediaTrackConstraints 继承自它并补充了高级约束字段。日常业务代码里，常见写法是：

const constraints: MediaTrackConstraints = {
  audio: {
    echoCancellation: true,
    noiseSuppression: true,
  },
};

这种写法可以编译通过，但它把 echoCancellation 限制成了简单的布尔字面量。如果项目需要实现智能协商，例如优先开启回声消除，但允许在硬件资源紧张时回退，规范要求使用带 ideal 的约束对象：

const constraints = {
  audio: {
    echoCancellation: { ideal: true },
  },
} satisfies MediaTrackConstraints;

严格来说，ConstrainBoolean 的定义由两部分组成：布尔值本身，以及包含 exact、ideal 两个可选属性的参数对象，这个对象被称为 ConstrainBooleanParameters。在 TypeScript 中自己定义并不复杂，但要注意和内置 lib.dom.d.ts 的全局类型声明保持边界。由于 interface 支持声明合并，同名且结构一致的接口可以共存，但结构冲突会直接编译失败。所以更推荐将这些类型收敛到业务模块中导出，而不是随手往全局作用域里塞。

export interface ConstrainBooleanParameters {
  exact?: boolean;
  ideal?: boolean;
}
export type ConstrainBoolean = boolean | ConstrainBooleanParameters;

建立回声消除专用的约束类型与工具函数

回声消除并不是孤立字段，它通常和 noiseSuppression、autoGainControl 等音频约束一起出现。为了让约束对象既保持标准结构，又能在编译期区分普通音频流和开启回声消除的音频流，可以定义一个从 MediaTrackConstraints 派生的类型别名：

export interface EchoCancellationAudioConstraints {
  echoCancellation?: ConstrainBoolean;
  noiseSuppression?: ConstrainBoolean;
  autoGainControl?: ConstrainBoolean;
}
export type EchoCancellationTrackConstraints = Omit<MediaTrackConstraints, 'audio'> & {
  audio?: EchoCancellationAudioConstraints;
};

这里没有直接 extends MediaTrackConstraints，而是用 Omit 先把 audio 属性移除，再交叉新的音频约束类型。原因是 MediaTrackConstraints 中的 audio 本身是宽泛的，可能是布尔值或约束对象；如果继承后直接覆盖为更窄的类型，在严格类型检查下容易出现属性不兼容。而 Omit 加交叉类型的方式可以更明确地表达：除了音频部分被替换，其余约束保持原样。

类型定义只是一半，实际运行还需要解析 true、false 和约束对象这三种形态。下面的工具函数把 ConstrainBoolean 转换成便于处理的统一结构，既不会改变给浏览器的原始语义，也能用于日志、权限提示和配置合并：

export function normalizeEchoCancellation(
  value: ConstrainBoolean | undefined
): { enabled: boolean; strength: 'default' | 'ideal' | 'exact' } {
  if (value === undefined) {
    return { enabled: false, strength: 'default' };
  }
  if (typeof value === 'boolean') {
    return { enabled: value, strength: 'default' };
  }
  return {
    enabled: value.exact ?? value.ideal ?? false,
    strength: value.exact !== undefined ? 'exact' : 'ideal',
  };
}

能力探测与 getUserMedia 的安全集成

类型再精确，也不能忽略浏览器能力差异。回声消除在某些移动端浏览器或隐私模式下不可用，如果直接写入 exact: true，一旦设备不支持就会抛出 OverconstrainedError。因此，在调用 getUserMedia 之前应先用 getSupportedConstraints 探测，再根据结果调整约束。

下面封装一个请求函数，它会保留调用方传入的偏好，同时在浏览器不支持时移除对应的约束字段，从而避免无意义的失败：

export async function requestEchoCancelledAudio(
  constraints: EchoCancellationTrackConstraints = {}
): Promise<MediaStream> {
  const supported = navigator.mediaDevices.getSupportedConstraints();
  const requestedAudio: EchoCancellationAudioConstraints = constraints.audio ?? {};
  const echoCancellation = requestedAudio.echoCancellation ?? true;
  const audioConstraints: EchoCancellationAudioConstraints = { ...requestedAudio };
  if (!supported.echoCancellation) {
    delete audioConstraints.echoCancellation;
  } else if (typeof echoCancellation === 'boolean') {
    audioConstraints.echoCancellation = echoCancellation;
  } else {
    audioConstraints.echoCancellation = { ...echoCancellation };
  }
  return navigator.mediaDevices.getUserMedia({
    video: false,
    audio: audioConstraints,
  });
}

获取到媒体流后，还可以通过 track.getSettings() 读取浏览器最终生效的值。这个方法返回的 MediaTrackSettings 中包含 echoCancellation，但它是实际运行结果，不再是约束对象。将实际结果和请求约束分开处理，可以避免把用户希望开启和浏览器确实开启混为一谈。下面这个函数用于快速检查当前轨道是否真的启用了回声消除：

export function isEchoCancellationEnabled(track: MediaStreamTrack): boolean {
  const settings = track.getSettings();
  return settings.echoCancellation ?? false;
}

模块化声明与全局类型扩展的取舍

很多人可能会想到直接在全局 MediaTrackConstraints 或 MediaTrackSettings 接口上补充类型。这在部分老项目里确实有用，但需要谨慎。TypeScript 的 lib.dom.d.ts 已经包含 WebRTC 相关接口，重复声明相同属性且类型相同是可以共存的；但如果未来的类型升级改变了字段定义，就可能产生冲突。因此如果你的项目需要长期维护，建议把自定义类型做成独立的 audio-constraints.ts 模块，而不是修改全局。

如果确实需要给一个还没有类型的自定义字段做全局声明，可以使用 declare global，但要确保文件是一个模块。下面这段代码仅作为扩展全局类型的一种示例，实际使用时请先确认标准库是否已经包含相同字段：

export {};
declare global {
  interface MediaTrackSupportedConstraints {
    echoCancellation?: boolean;
  }
}

在实际工程里，类型文件和运行时工具函数往往放在一起。你可以将 ConstrainBoolean、EchoCancellationTrackConstraints 和校验函数统一导出，再让音频采集模块通过具名导入使用。这样既不会污染全局命名空间，也方便在多个项目间复用。对于 getUserMedia 的约束参数，函数内部接收专用类型，对外仍然兼容标准 MediaStreamConstraints，因此可以平滑替换现有调用。

回声消除的类型定义本质上是在约束建模和浏览器实际行为之间找到平衡。用 ConstrainBoolean 而不是单纯的布尔值，能保留规范赋予的灵活性；用模块化导出而不是全局覆盖，则能让类型方案在长期演进中保持稳定。把类型声明、运行时校验和能力探测组合起来，TypeScript 项目就可以在编译期获得更准确的提示，同时在运行期更稳妥地处理音频处理差异。