できない.dev

TypeScript でオブジェクトリテラルに余分なプロパティを指定できない

「Object literal may only specify known properties」はオブジェクトリテラルに対する厳密チェック。
一度変数に代入する、型を拡張する、または index signature を加えると解消する。

公開: 更新:

症状できない · exit 2
npx tsc
src/bad.ts(3,21): error TS2353: Object literal may only specify known properties, and 'extra' does not exist in type 'Props'.
解決後できた · exit 0
npx tsc

2026-10-23 に node:20(TypeScript 5.9.3 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細

要約

TypeScript はオブジェクトリテラルに対して excess property check を行う。
「Object literal may only specify known properties, and 'foo' does not exist in type 'Bar'」は、このチェックで出るエラーである。
リテラルを直接渡すと型に無いプロパティが拒否されるが、変数経由で渡すか型を広げれば回避できる。

実行例

未定義のプロパティ extra を含むオブジェクトリテラルを関数にそのまま渡して、node:20 で TypeScript 5.9.3 の tsc を実行すると、3 行目に TS2353 が出て終了コードは 2 になる。
一度変数に入れてから渡すように書き換えると、エラーは消えて終了コードは 0 になる。

Version 5.9.3
$ npx tsc
src/bad.ts(3,21): error TS2353: Object literal may only specify known properties, and 'extra' does not exist in type 'Props'.
$ echo $?
2
$ npx tsc
$ echo $?
0

— 2026-10-23 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-23 検証(ほか 2 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5
  • TypeScript 5.9.3

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. 一度変数に入れる

excess property check は オブジェクトリテラルの直渡しのみ に効く。
変数に入れてから渡すと構造的部分型のチェックに切り替わり、追加プロパティが許される。

type Props = { name: string };
declare function render(p: Props): void;
 
// NG: excess property check
render({ name: "a", extra: 1 });
 
// OK: 変数経由
const obj = { name: "a", extra: 1 };
render(obj);

ただし「タイポをすり抜ける」副作用もあるため安易に使わない(公式ドキュメント(新しいタブで開く))。

2. 型に optional / index signature を追加する

将来的に拡張可能にしたい場合は型側を広げる。

type Props = {
  name: string;
  extra?: number;        // 任意プロパティを明示
};
 
type Loose = {
  name: string;
  [key: string]: unknown; // 任意キーを許可
};

[key: string]: T の index signature を入れると任意のキーを受け付けるようになる。

3. typo を直す

colour を color にするだけで解消するケースが意外と多い。
綴りの近いプロパティが型にあると、エラーは TS2561 になり、メッセージ末尾に Did you mean to write 'color'? と候補が出る。
この候補を信用する。

4. 最後の手段としての as

どうしても通す必要があるなら as で抑えるが、型安全性が崩れるので避ける。

render({ name: "a", extra: 1 } as Props);

ライブラリ側の型定義が古いだけなら、declare module で型のほうを上書きする。

よくある原因

  1. オブジェクトリテラルを直接渡している。
    TypeScript はリテラル経由の場合に限り、未定義プロパティを誤入力とみなして拒否する。
  2. 受け取る側の型が完全一致を要求している。
    関数引数や変数の型が optional プロパティを許しておらず、追加プロパティが想定されていない。
  3. 単純なタイポをしている。
    colour と color のような綴り間違いを、TypeScript が親切にエラーとして知らせている。
  4. 型の更新が漏れている。
    実装側で増やしたプロパティを、型定義に反映し忘れている。