在WebRTC应用里，媒体采集的清晰度、帧率、回声消除等能力并不是直接写死，而是通过约束条件交给浏览器去协商。TypeScript 在 lib.dom.d.ts 中为 MediaStreamTrack 提供了一套相当严谨的约束类型定义，但很多项目里仍然用 any 或 Record<string, unknown> 来绕过这些类型，结果就是运行时出现约束被忽略、参数类型不符等问题。理解 MediaTrackConstraints、MediaTrackConstraintSet 以及 Constrain 系列的联合类型，是写出类型安全采集逻辑的前提。

一、MediaTrackConstraints 与基础约束类型

MediaStreamTrack 的约束分为请求端和设置端。请求端通常来自 getUserMedia 的 video、audio 参数，类型是 MediaTrackConstraints。该接口继承自 MediaTrackConstraintSet，并额外允许传入布尔值表示是否启用某条轨道。MediaTrackConstraintSet 中的每个字段都使用了 Constrain 前缀的联合类型，而不是单一 number 或 string。这样设计是因为 WebRTC 规范允许一个约束既可以是具体值，也可以是带 min、max、exact、ideal 的范围对象。

在 TypeScript 标准库中，ConstrainULong 被定义为 number 与 ConstrainULongRange 的联合；ConstrainDouble 是 number 与 ConstrainDoubleRange 的联合；ConstrainDOMString 是 string、string 数组与 ConstrainDOMStringParameters 的联合；ConstrainBoolean 是 boolean 与 ConstrainBooleanParameters 的联合。这四个基础类型覆盖了轨道设置中绝大多数字段。下面这段代码展示了核心定义结构，为了便于理解省略了部分浏览器扩展字段。

interface MediaTrackConstraintSet {
  width?: ConstrainULong;
  height?: ConstrainULong;
  aspectRatio?: ConstrainDouble;
  frameRate?: ConstrainDouble;
  facingMode?: ConstrainDOMString;
  deviceId?: ConstrainDOMString;
  echoCancellation?: ConstrainBoolean;
  noiseSuppression?: ConstrainBoolean;
  latency?: ConstrainDouble;
  channelCount?: ConstrainULong;
}
type ConstrainULong = number | ConstrainULongRange;
type ConstrainDouble = number | ConstrainDoubleRange;
type ConstrainDOMString = string | string[] | ConstrainDOMStringParameters;
type ConstrainBoolean = boolean | ConstrainBooleanParameters;
interface ConstrainULongRange extends ULongRange {
  exact?: number;
  ideal?: number;
}
interface ConstrainDoubleRange extends DoubleRange {
  exact?: number;
  ideal?: number;
}
interface ConstrainDOMStringParameters {
  exact?: string | string[];
  ideal?: string | string[];
}
interface ConstrainBooleanParameters {
  exact?: boolean;
  ideal?: boolean;
}

可以看到，宽高、帧率、码率类数值约束都支持直接给数值，也支持给范围对象。范围对象又分两层：基础范围即 min 和 max，扩展范围即 exact 和 ideal。exact 表示必须精确匹配，如果浏览器找不到满足条件的设备或配置，getUserMedia 会直接失败。ideal 表示理想值，属于软约束，浏览器会尽量靠近但不保证满足。对于字符串类约束，如 facingMode 和 deviceId，既可以是单个字符串，也可以传字符串数组表示一组可接受的值，甚至可以传对象指定精确值和理想值。布尔类约束的 exact 和 ideal 也遵循同样的语义。

需要特别注意的是，TypeScript 类型并不能阻止你写出运行时无效的约束。例如给 width 传入一个负数，类型检查仍然会通过，因为 number 类型不区分正负。真正能提前发现问题的地方在于约束之间的冲突、exact 值超过 max 等逻辑错误。因此虽然类型定义已经比较完善，仍建议在封装采集逻辑时做一层轻量校验。

二、min、max、exact 与 ideal 的组合规则

当同一个约束上同时出现 min、max、exact 和 ideal 时，浏览器会按照确定优先级处理。exact 优先级最高，只要存在 exact，该约束就变成强约束，任何不满足的配置都不能被选用。min 和 max 构成可接受区间，浏览器会在这个区间内寻找最佳配置。ideal 是在区间内的软目标，如果区间内存在接近 ideal 的配置就选它，否则退而求其次。TypeScript 层面将 min、max 定义在基础范围接口中，把 exact、ideal 定义在扩展接口中，正好对应规范里的约束算法。

以下代码演示了如何用类型正确描述一个带范围约束的视频采集请求。这里没有使用任何 any，也没有做无意义的类型断言，编译期间就能保证每一个字段值符合 Constrain 联合类型。

const videoConstraints: MediaStreamConstraints = {
  video: {
    width: { ideal: 1280, max: 1920 },
    height: { ideal: 720, max: 1080 },
    frameRate: { ideal: 30, min: 24 },
    facingMode: ['user', 'environment']
  },
  audio: {
    echoCancellation: true,
    noiseSuppression: { ideal: true }
  }
};
const stream = await navigator.mediaDevices.getUserMedia(videoConstraints);

这里 width 和 height 都只给了 ideal 和 max，没有给 min，浏览器会把 min 当作设备能力下限，把 ideal 作为优先目标，在不超过 max 的前提下尽量选用 1280x720。frameRate 指定了 min 24 和 ideal 30，意味着至少 24 帧，最好 30 帧。facingMode 传入数组表示前后摄像头都可以，浏览器根据当前状态选择。audio 中的 echoCancellation 直接传 true，它等价于 exact: true，但在 MediaTrackConstraintSet 中直接写布尔值是被允许的。noiseSuppression 则使用 ideal: true，表示有降噪最好，没有也能接受。

实际开发中，一个常见的错误是把 ideal 和 exact 混为一谈。例如想尽可能获得 60 帧，却写成 frameRate: { exact: 60 }，万一设备不支持 60 帧就会导致采集失败。如果只是偏好高帧率，应该写成 frameRate: { ideal: 60, min: 30 }。TypeScript 无法帮你区分这种语义差异，但正确使用 Constrain 系列类型可以让团队在代码评审时更快发现这类问题。

三、MediaTrackSettings 与请求约束的类型差异

getUserMedia 成功后，通过 track.getSettings() 可以得到 MediaTrackSettings 对象。很多开发者以为它和 MediaTrackConstraints 是同一套类型，其实差别很大。MediaTrackSettings 里的每个字段都是具体值，不是范围对象，也不是 ideal 数组。例如 width 是 number，height 是 number，facingMode 是具体的 string。这是因为 getSettings 返回的是浏览器最终实际选定的配置，协商过程已经结束。

TypeScript 标准库中 MediaTrackSettings 的定义并没有用 Constrain 前缀类型。你无法把一个 settings.width 直接赋值给一个期望 ConstrainULong 的参数，因为 settings.width 是 number，而 number 恰好是 ConstrainULong 联合类型的一部分，所以某些情况下会出现类型兼容的假象。但 settings.facingMode 是 string，而约束端 facingMode 允许 string | string[] | object，反过来约束端可以兼容设置端，不代表它们是同一类型。更重要的是，getSettings() 可能返回 undefined，尤其是在轨道尚未激活时。

下面代码展示了如何安全地读取轨道设置，并用类型守卫把可能为 undefined 的值收窄为具体类型。这里的判断条件不仅满足 TypeScript，也符合运行时行为。

const videoTrack = stream.getVideoTracks()[0];
const settings = videoTrack.getSettings();
if (typeof settings.width === 'number' && typeof settings.height === 'number') {
  const actualWidth: number = settings.width;
  const actualHeight: number = settings.height;
  console.log(actualWidth, actualHeight);
}
if (settings.facingMode && settings.facingMode.length > 0) {
  const mode: string = settings.facingMode;
  console.log(mode);
}

上面的代码中，typeof settings.width === 'number' 不只是类型收窄，也是在处理某些浏览器实现中 settings 字段可能缺失或为 null 的兼容性问题。facingMode 的判断同样如此。通过这种方式，你不必使用 as number 这类断言，也就避免了把 undefined 误当成有效值的风险。

四、封装一个类型安全的约束构建函数

为了在多个页面或组件中复用采集逻辑，可以把常用的视频、音频约束抽成工厂函数。这样业务代码里不必反复声明 MediaStreamConstraints 类型，也能通过返回值类型自动获得检查。工厂函数内部仍然使用标准类型，外部调用时传参越界会直接报编译错误。

下面这个函数接收一个简单的偏好对象，返回完整的 MediaStreamConstraints。它用 mediaTrackConstraints 来组织 video 和 audio，避免函数返回类型被推断成过于宽泛的对象。

interface VideoPreference {
  width?: number;
  height?: number;
  frameRate?: number;
}
function buildConstraints(pref: VideoPreference): MediaStreamConstraints {
  const constraints: MediaStreamConstraints = {
    video: {},
    audio: {}
  };
  if (pref.width) {
    constraints.video!.width = { ideal: pref.width };
  }
  if (pref.height) {
    constraints.video!.height = { ideal: pref.height };
  }
  if (pref.frameRate) {
    constraints.video!.frameRate = { ideal: pref.frameRate, min: 24 };
  }
  constraints.audio = {
    echoCancellation: true,
    noiseSuppression: { ideal: true }
  };
  return constraints;
}
const myConstraints = buildConstraints({ width: 1280, height: 720 });

这里使用了非空断言符号 video!，因为我们知道 video 初始化为空对象。不过为了代码健壮性，更推荐在返回前一次性构造 video 对象，而不是先给空对象再逐个断言。比如可以直接声明一个 videoConstraint: MediaTrackConstraints['video'] 变量，类型收窄会更干净。实际项目中构建复杂约束时，应该尽量保持不可变风格，减少非空断言的使用。

五、总结与落地建议

TypeScript 对 MediaStream Track 约束类型的支持相当完整，核心是 Constrain 系列联合类型在 MediaTrackConstraintSet 上的映射。理解这些类型之后，再遇到传入约束不生效的问题，就可以从类型结构反推浏览器协商逻辑，而不是盲目修改参数。建议在项目中把 getUserMedia 封装成带类型参数的函数，内部只使用标准 Constrain 类型，避免 any 外泄。

同时要注意，TypeScript 类型只能保证结构和取值范围的一部分正确，无法验证约束语义是否合理。强约束 exact 使用不当会直接导致采集失败，ideal 使用不当又可能降低用户体验。因此类型安全加上对 WebRTC 约束算法的理解，两者缺一不可。