はじめに
「同じブラウザを使っているはずなのに、ユーザーによって挙動が異なる。」
こんな状況に遭遇したことはありませんか?
本記事では、ReactアプリケーションでのPDF表示機能実装時に遭遇した、Safari バージョン起因のエラーについて、原因調査から解決までのプロセスを共有します。
原因の特定
pdfjs-distを使ったPDF表示機能の動作確認中に起きたことです。
私の環境では、Edge、Safari、Chromeなど複数ブラウザで動作確認を行い、問題なく動作していたはずでした。
しかし、同僚から 「SafariでのPDF表示時にエラー出るけど、再現する？」 と確認があり、調査を始めました。
- ブラウザのキャッシュの問題？ → キャッシュクリアでは改善しない
- ユーザーの設定や拡張機能の違い? → Safariに拡張は導入しておらず、ライブラリのバージョンの条件も同じ
行き詰まったため、pdfjs-distのソースコードを確認しました。
すると、URL.parse()というWeb APIを使用していることを確認できました。（この辺）
const base = URL.parse(baseUrl);
このURL.parse()こそが今回の挙動の原因でした
URL.parse()とは
- MDN: URL: parse() 静的メソッド
MDNによるとURL.parse()は、文字列から安全にURLオブジェクトを作成するためのメソッドだそうです。
new URL()との違いは、無効なURL文字列を渡した場合に例外をスローせず、nullを返す点です。（try-catchで囲う必要がない）
注目すべきは、これが 比較的新しいweb API である点です。
Baseline 2024
Since September 2024, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.
このAPIは、2024年9月以降のブラウザのバージョンでしか動作しない のです！
Safariバージョンの違い
SafariでURL.parse()をサポートするようになったのは、v18.0のようです。(参考 Caniuse: URL.parse())
そこで、動作確認で使用したSafariのバージョンを確認したところ...
ビンゴでした！
私のSafariはv18系で、レビュワーのSafariはv17系だったため、動作の違いが発生していたのです。
対応
機能のリリースが、2025年中頃予定でした。
そのため、2024/9月以前のブラウザバージョンでの利用もサポートする必要がありました。
（Caniuse情報だと、この記事執筆時点の2025/12月時点でも、全体の2割のユーザーがURL.parse()非対応のブラウザを使っているようです。）
具体的な対応としては、pdfjs-distのlegacyビルドを使用することにしました。
legacyビルドでのみ、該当機能がポリフィルされているため、古いブラウザでも動作するようになります。
現時点では、pdfjs-distを使う際は大体のプロジェクトにおいてlegacyビルドの方が挙動安全そうです。
まとめ
自身で直接webAPIを呼び出す時は互換性を意識しやすいですが、ライブラリの内部実装で使用されている場合まで意識が及ばず、トラブルになってしまいました。
今回の経験から、以下の点を今後気を付けていこうと思いました。
- 新しいライブラリを導入する際は、使用しているWeb APIや対応ブラウザを確認する
- 動作確認する際は、ブラウザのバージョンを意識する
- 特にSafariのバージョンはMac OSのバージョンアップと連動しており、バージョン差異が生まれやすいので要注意！
- プロジェクトごとにサポートするブラウザバージョンを明確に定義し、確認不可を減らす