file:// と localhost は何が違う？ 同じHTMLなのに動いたり動かなかったりする理由

同じHTMLでも、ブラウザから見た実行環境は同じではない

問題を短くすると、HTMLの中身ではなく、そのHTMLへどう到達したかによってブラウザが適用するルールが変わります。file://ではファイルシステム上のファイルを直接開き、localhostではWebサーバーからHTTPレスポンスとして受け取ります。

その違いから、Origin、CORS、HTTPヘッダー、Web APIの利用条件、保存領域などに差が生まれます。コードを一切変更していなくても、開き方だけで動作差が出るのはこのためです。

file://は直接読み込み、localhostはHTTP配信

file://で開く場合、間にWebサーバーはいません。HTML、JavaScript、画像などはローカルファイルとしてブラウザから参照されます。localhostではブラウザが自分の端末上で動くWebサーバーへHTTPリクエストを送り、HTTPレスポンスとしてリソースを受け取ります。

localhostという名前が付いていても、それだけでクラウドへアップロードしているわけではありません。localhostは通常ループバック先として同じ端末を指します。ただし、ページ内のコードが別の外部URLへ通信することはできるため、『localhostだから通信しない』とも言えません。

大きな違いの一つがOrigin

通常のWebページでは、Originはおおまかにscheme・hostname・portの組み合わせで決まります。たとえばhttp://localhost:8080から配信されたページと同じOriginのリソースなら、同一Originとして扱いやすくなります。

file URLは特殊です。MDNでは、現在のブラウザはfile:///で読み込まれたファイルを通常opaque originとして扱うと説明しています。opaque originは他のOriginと同一とは判定されないため、同じフォルダにある別ファイルでも自動的に同一Originとはみなされません。なお、file URLのOriginの扱いには実装依存の部分もあります。

JavaScript Moduleやfetchで差が出やすい

分かりやすい例がJavaScript Moduleです。HTMLから別ファイルのModuleを読み込む構成をfile://で試すと、Moduleのセキュリティ要件によってCORSエラーになることがあります。MDNも、Moduleをローカルファイルとして試すのではなくサーバー経由でテストするよう案内しています。

fetchで隣のJSONやテキストを読む構成でも同様です。ファイルが同じフォルダに存在していても、それだけでJavaScriptから自由に読めるとは限りません。localhostなら、そのファイルを同じHTTP Originからレスポンスとして返す構成にできます。

localhostにはHTTPレスポンスがある

localhostではWebサーバーが応答するため、Content-Type、Content-Length、Content-Range、Content-Security-Policy、Cross-Origin-Opener-Policy、Cross-Origin-Embedder-Policyなど、用途に応じたHTTPヘッダーを返せます。file://にはサーバーから返されるHTTPレスポンスそのものがありません。

メディア再生ではこの違いが具体的に現れます。HTTP Range Requestは、動画プレーヤーなどが大きなリソースの必要な範囲だけ取得するために使えます。Browser Kittyのローカルプレビューサーバーでも紹介動画のRange Requestを処理しています。実装中には、シークなどで古いRange接続をブラウザが閉じたあと、サーバーがその接続へ書き込もうとして例外になる問題もありました。HTMLだけでなく、Webサーバー側の振る舞いもlocalhost環境の一部です。

Secure Contextだけでは説明できない

『file://は安全ではないから動かず、localhostは安全だから動く』と整理すると不正確です。Secure Contextの仕様ではlocalhostのようなループバック先は開発環境として潜在的に信頼できるOriginとして扱われます。またfile schemeも潜在的に信頼できる対象として扱われます。

つまり、file://とlocalhostの違いをSecure Contextだけで説明することはできません。実際には、Origin、URL scheme、CORS、API固有の条件、権限、ユーザー操作などを分けて見る必要があります。

Secure Contextでも、file://では使えないAPIがある

Service Workerが分かりやすい例です。Service WorkerはSecure Context向けの機能ですが、register()へ渡すscript URLやscope URLにはさらに条件があり、http:またはhttps:以外のschemeはTypeErrorになるとMDNに記載されています。localhostはローカル開発用のSecure ContextとしてService Workerを利用できますが、file://のHTMLからfile:のService Workerをそのまま登録することはできません。

このように、『Secure Contextである』はWeb API利用条件の一部にすぎません。ある機能がfile://で動くかを判断するときは、そのAPI固有の仕様まで確認する必要があります。

localStorageもfile://では同じ前提にできない

通常のWebサイトではlocalStorageはOriginごとに分かれます。http://localhost:8080で開くページなら、そのOriginに対応する保存領域として考えられます。

一方、MDNではfile: URLから読み込んだ文書のlocalStorageの要件は未定義で、ブラウザによって挙動が変わり得ると説明しています。現在はfile URLごとに別の保存領域のように見えるブラウザがあっても、それを将来も保証される仕様として依存するべきではありません。単一HTMLで設定や作業状態を保存する場合は、この差も考慮が必要です。

だからBrowser Kittyではfile://とlocalhostを別々に確認する

Browser Kittyでは、可能なツールを単一HTMLとして配布できる構成にしています。JavaScript、CSS、SVG、Worker、Wasmなどを可能な範囲で1ファイルへまとめれば、隣のファイルをfetchしたりModuleとして読み込んだりする必要が減り、file://でも成立しやすくなります。これは配布しやすさだけでなく、ローカルファイル特有の制約を減らす意味もあります。

一方、開発時にはlocalhostでも確認します。Web版としてのMIME type、Range Request、CSP・COOP・COEPなどをHTTPレスポンスヘッダーとして設定した場合の挙動など、HTTP配信して初めて確認できる部分があるからです。単一HTMLで動いたからWeb版も同じ、localhostで動いたからダブルクリックでも同じ、とは限りません。

同じHTMLなのに動作が違うときは、コードだけでなくアドレスバーも確認します。file://なのか、http://localhostなのか、公開されたhttps://なのか。Webアプリでは、その違いも実行環境の一部です。

注意点

• 『file://で開ける』と『完全ローカル処理』は同じ意味ではありません。file://のHTMLでも、CORSなど相手側の条件を満たせば外部URLへ通信するコードを実行できます。
• localhostは通常自分の端末へ戻るループバックですが、ページ内の外部通信まで止める仕組みではありません。NetworkパネルやCSPなどで別に確認します。
• 単一HTML化で別ファイル読み込みの問題は減らせますが、API自体がhttp: / https:や特定のOrigin条件を要求する場合まで回避できるわけではありません。