こんにちは！ 2025年1月にジンジャーにジョインしたプロダクト開発部の今道です。
今回、ありがたいことにテックブログ執筆の機会をいただきました。私自身、これまでさまざまな企業のテックブログを読んできたので、「ついに自分も書く側になるのか！」と密かに喜んでいます。
さて、今回は私がジンジャーでの業務中にハマった package.jsonのバージョン固定 にまつわるトラブルと、その解決策についてお話しします。
事象の発生：ローカルでは動くのに開発環境で落ちる⁉
私が担当しているAPIはTypeScriptで実装されており、開発の流れは以下のようになっています。
- ローカルで実装
- 自動テストを実行
- 問題なければ
developブランチにマージし、開発環境で動作確認
この手順で進めていたのですが、ある日 ローカルでは問題なく通っていたテストが、開発環境では失敗する という事態に遭遇しました。
エラー内容は、 TypeScriptの型の不一致 によるもの。
私の担当箇所ではなかったのですが、
「ローカルでは動いていたのに、なぜ開発環境で落ちるのか？」
という疑問を持ち、調査を開始しました。
原因調査：バージョン管理の落とし穴
最初にチーム内で原因を検討したところ、 ライブラリのバージョンアップの影響では？ という仮説が浮かびました。
そこで、 package.json の記述を確認すると、 バージョンが完全に固定されていない ことが判明しました。
「^」「~」が引き起こした問題
package.json のバージョン指定には、以下のような記号を使うことがあります。
-
^1.2.3→1.3.0や1.4.0にアップデートされる可能性あり -
~1.2.3→1.2.4や1.2.5にアップデートされる可能性あり
つまり、「最新のバージョンを許容する」設定 になっていたのです。
さらに、開発環境では 毎回 npm install を実行 していたため、最新のパッチバージョンが自動的に適用されていました。その結果、ライブラリのアップデートにより 型の厳密化 が行われ、エラーが発生してしまったのです。
実際に、ローカル環境でも npm install を実行してライブラリを最新化したところ、同じエラーが再現しました。
具体的なエラーと修正対応
発生したエラー
const payload = ...;
const secretOrPrivateKey = ...;
const options = { expiresIn: `1h` };
const token = jwt.sign(payload, secretOrPrivateKey, options);
エラー内容：
「この呼び出しに一致するオーバーロードはありません。」
修正後のコード
const payload = ...;
const secretOrPrivateKey = ...;
const options: jwt.SignOptions = { expiresIn: `1H` };
const token = jwt.sign(payload, secretOrPrivateKey, options);
型を jwt.SignOptions で明示的に指定することで、エラーを回避しました。
恒久対応：バージョン固定と定期アップデートのルール化
一時的な対応だけでは不十分 なので、今後同じ問題が起きないように対策を検討しました。
最終的に採用した方針
✅ package.json のバージョンを 完全に固定 する
✅ 定期的にバージョンを メンテナンスするルールを策定
✅ CI を活用して ライブラリ等の更新版の自動検知 を検討
これにより、開発環境とローカル環境のライブラリバージョンを統一しつつ、適切なタイミングで更新できる 体制を整えました。
バージョン固定のメリット・デメリット
| メリット | デメリット | |
|---|---|---|
| ✔ メリット |
突発的なバグの発生を防げる → 開発環境とローカル環境の不一致がなくなる |
アップデートが遅れがちになる → 最新版との差が開く |
| ✔ メリット |
環境差異がなくなる → チーム全員で同じ環境で開発できる |
緊急対応が難しくなる → 脆弱性対応時にすぐ更新できないリスク |
| ✔ メリット |
管理の手間が減る → 毎回の npm install でのバージョン差異に悩まなくなる |
CI での監視が必要 → 更新を忘れると技術的負債になりやすい |
このデメリットを補うために、CI で定期的に依存関係の更新チェックを行う 仕組みを取り入れる予定です。
まとめ：エンジニアとして成長できる環境で一緒に働きませんか？
今回は、 package.json のバージョンを完全に固定することで、突発的なエラーを防ぐことができました。
しかし、ただ「バージョンを固定する」だけではなく、定期的にメンテナンスする運用ルール も重要であると学びました。
この一件を通して、チーム内の議論が活発になり、「どうすればより良い開発環境を作れるか？」 を深く考えるきっかけになったことも嬉しく思います。
ジンジャーでは、エンジニア同士で議論しながら、より良い開発環境を目指す文化 があります。
もし、技術的な課題に向き合いながら成長したい方 や、チームでの開発を楽しみたい方 は、ぜひ一度お話ししましょう！
ジンジャーは 日本一の開発組織 を目指しています。
あなたの力をぜひ貸してください！ 🚀
Discussion