導入
TypeScriptを書いていると、赤い波線が消えた瞬間に「動いた!」と思ってしまうことがあります。僕も駆け出しの頃はそうでした。でも実際には、型エラーは消えたのに実行時に undefined is not a object が出ていたり、APIから返ってきた値の形が思ったものと違っていて画面が白くなったりすることがあります。最初は「TypeScriptを使っているのに、なぜバグが残るんだろう」と不思議に感じていました。
現場に入って何度か失敗を重ねた後に気づいたのは、TypeScriptのデバッグは「型を直すこと」だけでなく、「何が本当に入ってくる値なのか」を確認していく作業に近いということです。エラー文を読む、型を疑う、小さいコードで再現する、ログを出す、デバッガーで止める。このあたりを順番にやれるようになると、焦る時間がかなり減ります。
もちろん、最初からきれいにデバッグできる人はいません。僕も最初はエラー文を半分しか読まずに検索したり、とりあえず as any で逃がしたり、ログを大量に出して自分でも何が何だかわからなくなったりしていました。でも、少しずつやり方を変えるだけで「どこを見ればよさそうか」が分かるようになりました。この記事では、僕が現場で効いたと感じているTypeScriptのデバッグのコツを、少し先の先輩として共有します。
✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨
スイカゲームとにゃんこ大戦争のようなタワーディフェンス系ゲームを組み合わせたゲームを作成しました!
遊んでみていただけると嬉しいです🙇♂️
ハジメル.dev: https://hajimeru-dev.vercel.app/
「ひとりで続けるのは難しい」「何から学べばいいか分からない」という方向けに、
プログラミングのマンツーマンレッスンサービス「ハジメル.dev」も運営しています。
未経験OK・オンライン完結・月額制/違約金なしなので、気軽に無料相談してみてください🙇♂️
海外テックニュースを追いたいけど、英語や情報量の多さで大変…という方向けに、
Hacker News の話題を日本語でサクッと追える「HackerNews 日本語まとめ & AI要約」
を個人開発しました!
技術トレンド収集に使ってもらえると嬉しいです🔥🙇♂️
→ HackerNews 日本語まとめ & AI要約: https://hn-matome-2ht.pages.dev/
「ニャンパイアサバイバー」というヴァンパイアサバイバーリスペクトのゲームを作成しました!
もしよろしければ遊んで頂けると嬉しいです😭
習い事教室の先生向けに、SNS 投稿・生徒募集・保護者通知の文章を AI で生成する Web サービス「おしらせAI」を個人開発しました。Next.js + Supabase + LLM で構成しており、無料で月 10 回まで試用できます。よければ触ってみてください。
→ おしらせAI: https://oshirase-ai.vercel.app/
✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨
エラー文を最後まで読む
TypeScriptで一番最初にやることは、意外と「エラー文を最後まで読むこと」です。特に初心者だった頃の自分は、エラー文の最初の数行だけ見て「たぶんこれだ」と決めつけていました。でも実際には、重要なヒントが下の行にあることが多かったです。
たとえば次のようなエラーが出たとします。
const user = response.data.user;
console.log(user.name);
この時に出るエラーが、Property 'user' does not exist on type 'ApiResponse' なのか、Object is possibly 'null' なのか、Property 'name' does not exist on type '{}' なのかで、見るべき場所は全然違います。最初の文だけ見て「APIの型が間違っている」と思い込んで修正すると、実は response.data が配列だった、とか、user は存在するけど nullable だった、という別の問題を見逃すことがあります。
僕の失敗例では、ある画面で「ユーザー名が表示されない」という不具合がありました。最初はコンポーネント側の描画処理が悪いと思い、何度も JSX やテンプレートを書き換えました。でも結局、APIの型定義で user: User になっていたのに、実際の一部のレスポンスでは user: null が返ってきていました。エラー文には possibly 'null' と出ていたのに、当時の僕はそこを軽く見ていました。
デバッグする時は、エラー文を「怒られた文章」ではなく「ヒントのリスト」だと思って読むと楽になります。特にTypeScriptでは、型名・プロパティ名・行番号・possibly・not exist・is not assignable といった単語が重要です。全部を理解できなくても、まずは「どこが疑われているのか」だけ拾うだけでも、かなり前に進めます。
型エラーを「直す」ではなく「意味を確認する」
TypeScriptでよくある失敗は、型エラーを「消すこと」をゴールにしてしまうことです。僕も駆け出しの頃は、赤い波線が消えれば合格だと思っていました。そのため、迷うと any や as any を使って無理やり通すことがありました。確かにその場ではエラーが消えます。でも、それはバグを直したというより、TypeScriptに「もう見なくていいよ」と言わせてしまっているだけでした。
たとえば、次のようなコードです。
type User = {
id: number;
name: string;
};
function renderUser(user: User) {
return user.name;
}
const data = await api.getUser();
renderUser(data);
ここで data の型が unknown や ApiResponse<User> だった場合、as User を使えば一瞬で通ります。でも本当に data が User として安全なのかは別問題です。APIが失敗した時の型、データが未取得の時の型、一部の項目が省略される可能性がある型を無視すると、実行時に画面が壊れることがあります。
僕が意識するようになったのは、型エラーが出た時に「この型は何を保証しているのか」と考えることです。string なら文字列であることは保証されていますが、空文字ではないことは保証されていません。配列なら Array であることは保証されていますが、中身が必ず1件以上あることは保証されていません。User | null なら、nullの可能性をコードで分ける必要があります。
実務では、次のようにguard条件を入れるだけでもかなり楽になります。
function renderUserName(user: User | null) {
if (!user) return "未ログイン";
return user.name;
}
また、APIレスポンスのように外から来る値は、そのまま信用しすぎない方が安全です。可能なら受け取り時に型チェックを入れる、少なくとも重要な画面では null や undefined の分岐を残す、という考え方が役に立ちました。型エラーは面倒ですが、実は「ここを雑に扱うと危ないよ」と教えてくれているサインでもあります。
まずは小さい再現コードで切り分ける
バグが起きた時、いきなり大きな画面や複雑な処理の中に入っていませんか。僕も昔は、エラーが出た場所に近づこうとして、関連しそうなファイルを次々と開いていました。結果として、どこを変更したのか自分でも分からなくなり、余計に混乱することがありました。
TypeScriptのデバッグで特に効くのは、問題を小さいコードに切り出すことです。たとえば、ある関数で型エラーが出ているなら、その関数だけを別ファイルにコピーして、最低限の引数と戻り値で再現できないか試します。画面全体で起きている問題でも、原因は「APIレスポンスの型」「配列の扱い方」「条件分岐」「非同期のタイミング」のどれかに絞れることが多いです。
僕が経験した例では、リスト画面で「表示される時とされない時がある」という不具合がありました。最初はコンポーネントの描画ロジックが悪いと思い、何度も書き換えました。でも、小さいコードで試してみると、原因は配列のフィルタ処理にありました。
const activeUsers = users.filter((user) => user.status === "active");
const firstUser = activeUsers[0];
console.log(firstUser.name);
このコードは、activeUsers が空配列の場合に firstUser が undefined になります。TypeScriptの設定によってはここでエラーが出ますし、出ない場合でも実行時に落ちます。小さいコードにすると、filter の結果が空になる可能性があることがはっきり見えます。
再現コードを作る時は、依存関係をできるだけ減らすのがコツです。画面全体ではなく関数単位、API全体ではなく受け取った値の加工部分、ビルド全体ではなくその型定義部分だけに絞ります。最初は「これくらい単純で大丈夫かな」と思うくらい小さくて構いません。むしろ、小さくした方が本質が見えやすいです。問題が再現できない場合は、削りすぎた可能性があるので、少しずつ戻しながら原因を探します。
ログとデバッガーを使い分ける
僕は longtemps、デバッグといえば console.log だと思っていました。今でもログは便利です。特に非同期処理やAPIレスポンス、条件分岐の直後は、実際にどんな値が流れてきているかを見るのに役立ちます。
const response = await api.getUser();
console.log("response:", response);
const user = response.user;
console.log("user:", user);
if (!user) {
console.warn("user is null");
return;
}
ただ、ログを大量に出すと逆に分かりにくくなります。僕も過去に、関係ない変数を十数個出して、コンソールを見ながら「どれが本当の原因だろう」と迷ったことがあります。ログを出す時は、目的を一つに絞るのがおすすめです。「この値は null なのか」「この配列は空なのか」「この条件に入っているのか」。これを確認するためのログなら、少なくて十分です。
一方で、値の流れを追いかけたい時はデバッガーも便利です。VS Codeならブレークポイントを置いて、変数の値を watch できます。ログだと毎回実行し直す必要がありますが、デバッガーならその場で値を確認できます。
function calculateTotal(items: number[]) {
let total = 0;
for (const item of items) {
total += item;
}
return total;
}
もし calculateTotal の結果がおかしいなら、items が想定通りの配列なのか、total が途中でどう変化しているのかを止めて確認できます。TypeScriptのコードでも、最終的にはJavaScriptとして動くため、デバッガーはかなり有効です。
僕の場合は、簡単な型エラーは型定義を見ながら直し、値の流れが分からない時はログを出し、条件分岐やループで止まりたい時はデバッガーを使う、という使い分けをしています。全部を一人でやろうとすると疲れるので、「今は値を見たいのか」「型の保証を確認したいのか」「実行順序を確認したいのか」を先に決めると、かなり楽になります。
まとめ
TypeScriptのデバッグで一番大事なのは、焦ってすぐに型を変えないことだと思っています。エラー文を読む、型が本当に保証していることを確認する、小さいコードで再現する、ログやデバッガーで値を見る。この順番で考えると、意外と道筋が見えてきます。
僕自身も、最初は赤い波線を消すことばかり気にしていました。でも現場で何度か失敗するうちに、TypeScriptの型エラーは邪魔なものではなく、「ここを雑に扱うと後で困るよ」と教えてくれる存在だと感じるようになりました。もちろん、すべてを完璧に扱うのは難しいです。APIの仕様が変わることもあれば、古いコードの型が甘いこともあります。それでも、一つずつ確認していくことで、確実に成長できます。
これからTypeScriptでハマった時は、まず深呼吸して、エラー文の最後の行まで読んでみてください。そして「この値は何型なのか」「nullやundefinedの可能性はないか」「本当に小さいコードでも再現するか」を順番に確認してみてください。最初は時間がかかっても、その積み重ねが自信になります。少しずつでいいので、TypeScriptと一緒にバグと向き合っていけると、きっと開発がもっと楽しくなります。