Node ERR_INVALID_ARG_VALUE — 参数类型或取值范围错误

症状

遇到“Node ERR_INVALID_ARG_VALUE — 参数类型或取值范围错误”时靠猜测只会浪费时间。请按证据排查：先复现症状，再执行针对性诊断，定位根因后修复，并用明确检查验证结果。

可观察到的症状包括：

• Node 抛出 “TypeError [ERR_INVALID_ARG_VALUE]: The argument … is invalid”
• 错误堆栈指向 Node 内部而非你的代码
• 使用字面量时正常，使用变量时失败

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

node -e "try{ Buffer.alloc(-1) }catch(e){ console.log(e.code, e.message, e.stack.split('\n')[1]) }"

错误码与第一个应用堆栈帧能指出是哪个参数出错、从何处传入。

步骤 2

console.log({ type: typeof size, value: size, isNaN: Number.isNaN(size) })

字符串 “10” 与数字 10、或解析失败得到的 NaN，都会触发该错误。

常见诱因（按出现频率排序）：

• 传入了超出允许范围的值，如负数缓冲区大小或非法编码名
• 内置 API 收到错误的类型（该传数字却传了字符串）
• 配置或环境变量为空，产生了 undefined 或非法值

根因

Node 内置函数用严格校验检查参数。类型错误或超出范围的值会在真正执行前快速失败，抛出 ERR_INVALID_ARG_TYPE 或 ERR_INVALID_ARG_VALUE，因此堆栈会深入到 Node 内部。

修复

在边界处转换并校验输入：用 Number()/parseInt 解析数值字符串并检查 Number.isFinite，断言取值范围，之后再调用内置 API。

注意：Number() 会接受 “1e3” 与 “0x10”；若需严格十进制输入，应在转换前校验原始字符串。

function allocBuffer(raw) {
  const size = Number(raw);
  if (!Number.isInteger(size) || size < 0 || size > 1024) {
    throw new RangeError(`invalid buffer size: ${JSON.stringify(raw)}`);
  }
  return Buffer.alloc(size);
}

验证

用合法输入重跑并确认无错误。补充覆盖 undefined、空字符串与越界值的单元测试，锁定边界校验。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。