TypeScript TS2554 — 参数个数不符

症状

错误“TypeScript TS2554 — 参数个数不符”指向一个明确的失效模式。下面依次给出症状、定位该原因的检查命令、根本原因、修复方案，以及证明修复有效的验证步骤。

可观察到的症状包括：

• error TS2554: Expected 2 arguments, but got 1
• 新增可选参数后既有调用点报错
• 显式传入 undefined 会改变实参个数

诊断

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

步骤 1

npx tsc --noEmit 2>&1 | grep TS2554

消息给出期望个数，便于与调用点对比。

步骤 2

grep -rn "function name\|name(" src/ | head

查看参数列表可看出哪些实参可选或必填。

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

• 省略了必填参数，或传入了过多实参
• 回调签名与期望不符
• 重载解析选中了调用不满足的签名

根因

TypeScript 会依据解析出的签名校验实参个数，统计必填参数。遗漏必填实参，或传入超过签名可接受的实参，都报 TS2554。

修复

传入必需实参，为确实可选的参数标注 ? 或给默认值，可变参数用 rest，并修改签名而非转换调用。

注意：对函数转换或对调用使用 as any 会破坏实参个数检查并掩盖真实错误。

function createUser(name: string, age: number, role = 'member'): User { /*...*/ }

// ❌ createUser('alice');              // TS2554: expected 2-3, got 1
createUser('alice', 30);              // ✅ default applies
createUser('alice', 30, 'admin');     // ✅ explicit

// rest parameters for variadic
function log(...parts: unknown[]): void { console.log(...parts); }

验证

运行 tsc –noEmit 并确认 TS2554 消失；用单元测试确保运行期收到所需的值。

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

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