Content-Dispositionとは？ファイルダウンロードとファイル名について調べてみた

はじめに#

ファイルダウンロードの仕組みを自作しているときに、Content-Disposition というHTTPヘッダーが出てきた。

最初は、

「ファイルをダウンロードさせるために必要なもの」

くらいの認識だった。

ところが、実際に調べてみると、いくつか気になることが出てきた。

Content-Type もファイルの種類を表しているのに、なぜ Content-Disposition も必要なのか？

また、

• Content-Disposition がなくてもファイルを取得できるのか
• inline と attachment は何が違うのか
• filename を指定するとChromeではどう動くのか
• 日本語のファイル名はどう指定するのか
• filename と filename* は何が違うのか
• 両方指定した場合はどちらが使われるのか

といった疑問も出てきた。

そこで今回は、Node.jsで簡単なHTTPサーバーを作り、Chromeで実際の挙動を確認しながら調べてみた。

まず結論#

今回調べてみて、最初に考えていた、

「ファイルをダウンロードさせるには Content-Disposition が必要」

という理解は、少し違っていた。

Content-Disposition は、単純に「ファイルをダウンロードさせるためだけ」のヘッダーではない。

HTTPレスポンスでは、たとえば次のような指定ができる。

Content-Disposition: inline

Content-Disposition: attachment

inline はコンテンツを通常の表示方法で扱うことを示し、attachment はダウンロードする添付ファイルとして扱うことを示す。さらに、filename や filename* を指定することで、保存時などに使うファイル名についても情報を伝えられる。RFC 6266では、これらの用途が定義されている。

一方、Content-Type は、そのデータがどのようなメディアタイプなのかを示すヘッダー。

そのため、ざっくり整理すると次のようになる。

filename* は拡張パラメータ形式を使って値の文字コードを指定でき、RFC 8187ではUTF-8をサポートすることが定義されている。

ただし、仕様としての定義と、実際のブラウザの挙動が常に同じとは限らない。

そのため、今回はChromeで実際に確認してみる。

Content-Dispositionとは？#

Content-Disposition: inline

Content-Disposition: attachment

Content-Typeとの違い#

今回、最初に気になったのがここ。

たとえばJPEG画像を返す場合、

Content-Type: image/jpeg

とする。

これは、

「このデータはJPEG画像です」

という情報。

一方、

Content-Disposition: attachment

は、

「このレスポンスは添付ファイルとして扱います」

という情報。

つまり、

Content-Type
    ↓
「これは何のデータ？」

Content-Disposition
    ↓
「そのデータをどう扱う？」

という違いとして考えると分かりやすい。

Content-Type はメディアタイプを示し、Content-Disposition はコンテンツの扱い方を示す。

なぜContent-Dispositionが必要になったのか？#

Content-Type: image/jpeg

Content-Disposition: attachment

Content-Dispositionにはどのような指定がある？#

今回の記事では、主に次の4パターンを確認する。

さらに、ファイル名について、

filename="sample.txt"

と、

filename*=UTF-8''...

の違いも確認する。

実際にContent-Dispositionを試してみる#

今回確認したこと#

今回の検証では、以下を確認する。

1. Content-Disposition がない場合、Chromeはどう扱うのか
2. inline と attachment では何が変わるのか
3. filename を指定すると保存ファイル名が変わるのか
4. スペースを含むファイル名はどう扱われるのか
5. 日本語を filename に直接指定するとどうなるのか
6. filename* を使うとどうなるのか
7. filename と filename* を両方指定するとどちらが使われるのか
8. JPEGでも同じような挙動になるのか

検証方法#

今回の検証では、ChromeのDevToolsを利用する。

基本的に確認するのは次の3つ。

Response Headers

検証1：Content-Dispositionを指定しない#

まずは Content-Disposition をいっさい指定しないケース。

今回使用するTXTでは、

Content-Type: text/plain

だけを返す。

case '/case01-no-disposition-txt':
  sendText(res);
  break;

function sendText(res, contentDisposition) {
  res.setHeader('Content-Type', 'text/plain');

  if (contentDisposition !== undefined) {
    res.setHeader('Content-Disposition', contentDisposition);
  }

  res.end(txtData);
}

検証2：inline#

次に、

Content-Disposition: inline

を指定してみる。

case '/case02-inline-txt':
  sendText(res, 'inline');
  break;

Content-Disposition: inline

検証3：attachment#

次に、

Content-Disposition: attachment

を指定してみる。

case '/case03-attachment-txt':
  sendText(res, 'attachment');
  break;

Content-Disposition: attachment

検証4：filenameを指定する#

ここからファイル名指定を確認してみる。

Content-Disposition: attachment; filename="sample.txt"

case '/case04-filename-txt':
  sendText(
    res,
    'attachment; filename="sample.txt"'
  );
  break;

Content-Disposition: attachment; filename="sample.txt"

検証5：スペースを含むfilename#

次に、

Content-Disposition: attachment; filename="sample file.txt"

を試してみる。

ファイル名にスペースなどを含める場合、filename の値を引用符で囲む形式が利用できる。

case '/case05-filename-space-txt':
  sendText(
    res,
    'attachment; filename="sample file.txt"'
  );
  break;

Content-Disposition: attachment; filename="sample file.txt"

検証6：filenameに日本語を直接指定する#

ここで、次のような日本語ファイル名を指定してみる。

Content-Disposition: attachment; filename="日本語.txt"

case '/case06-filename-japanese-txt':
  sendText(
    res,
    'attachment; filename="日本語.txt"'
  );
  break;

TypeError
ERR_INVALID_CHAR

検証7：filename*を使う#

ここで filename* を試してみる。

たとえば、

Content-Disposition: attachment; filename*=UTF-8''%E6%97%A5%E6%9C%AC%E8%AA%9E.txt

とする。

filename* は拡張パラメータ形式を使用し、文字コードを指定した値を表現できる。RFC 8187では、UTF-8''... のような形式で文字コードと値を指定する。

case '/case07-filename-star-txt':
  sendText(
    res,
    "attachment; filename*=UTF-8''%E6%97%A5%E6%9C%AC%E8%AA%9E.txt"
  );
  break;

Content-Disposition: attachment; filename*=UTF-8''%E6%97%A5%E6%9C%AC%E8%AA%9E.txt

検証8：filenameとfilename*を両方指定する#

次に、2つを同時に指定してみる。

Content-Disposition: attachment;
 filename="fallback.txt";
 filename*=UTF-8''%E6%97%A5%E6%9C%AC%E8%AA%9E.txt

RFC 6266では、両方が存在する場合、filename* を理解するユーザーエージェントは filename* を選択することが推奨されている。古いユーザーエージェントへのフォールバックとして filename と filename* の両方を指定する形も示されている。

case '/case08-filename-both-txt':
  sendText(
    res,
    "attachment; filename=\"fallback.txt\"; filename*=UTF-8''%E6%97%A5%E6%9C%AC%E8%AA%9E.txt"
  );
  break;

Content-Disposition: attachment; filename="fallback.txt"; filename*=UTF-8''%E6%97%A5%E6%9C%AC%E8%AA%9E.txt

仕様上の説明
        ↓
filename* が優先される

実際のChrome
        ↓
filename* の指定 (日本語.txt) で保存された

比較
        ↓
一致した

検証9：inline + filenameをJPEGで確認する#

ここからJPEGを使ってみる。

レスポンスを次のように設定。

Content-Type: image/jpeg
Content-Disposition: inline; filename="sample.jpg"

case '/case09-inline-filename-jpg':
  sendJpeg(
    res,
    'inline; filename="sample.jpg"'
  );
  break;

Content-Type: image/jpeg
Content-Disposition: inline; filename="sample.jpg"

検証10：JPEG + attachment#

最後に、同じJPEGを attachment にしてみる。

Content-Type: image/jpeg
Content-Disposition: attachment; filename="sample.jpg"

case '/case10-attachment-jpg':
  sendJpeg(
    res,
    'attachment; filename="sample.jpg"'
  );
  break;

Content-Type: image/jpeg
Content-Disposition: attachment; filename="sample.jpg"

検証結果をまとめる#

10個の検証を実施したら、最後に表で比較する。

実際に調べて分かったこと#

注意点#

今回の検証は、以下の環境で実施している。

• Windows 11
• Node.js v24.14.1
• Google Chrome
• Node.js標準のHTTPサーバー

そのため、今回のChromeで確認した結果を、そのまま「すべてのブラウザで同じ」と考えることはできない。

特にファイル名については、ブラウザや保存先のファイルシステムによって調整される場合がある。MDNでも、ブラウザがファイルシステム上の制約に合わせてファイル名を変換する場合があると説明されている。

また、Content-Disposition がなくてもブラウザがリソースを取得したり保存したりする場合がある。

今回調べて分からなかったこと#

今回の記事ではChromeに絞って検証している。

そのため、次のような内容は今回の調査範囲外。

• FirefoxやSafariでの挙動
• <a download> を利用したダウンロードとの関係
• 複数ブラウザ間での filename / filename* の比較
• Windows以外のファイルシステムでのファイル名処理
• 長すぎるファイル名の詳細な挙動

また時間あるときにでも、調査してみようかな、、、

まとめ#

今回は、ファイルダウンロードを自作しているときに気になった Content-Disposition について調べた。

最初は、

「ファイルをダウンロードさせるために必要なヘッダー」

という認識だった。

しかし、調査と検証を通して、より正確には、

• Content-Type はデータの種類を示す
• Content-Disposition はコンテンツの扱い方を示す
• inline は通常の表示として扱う指定
• attachment は添付ファイルとして扱う指定
• filename で保存時などに利用するファイル名を示せる
• filename* で文字コードを指定できる形式でファイル名を示せる
• filename と filename* を両方指定する方法もある

ということが分かった。

最初に疑問だった、

「Content-Type があるのに、なぜ Content-Disposition も必要なの？」

については、

Content-Type と Content-Disposition は、そもそも伝えている情報が違うから

という結論になった。

また、

「Content-Disposition がないとファイルをダウンロードできないの？」

については、単純に「必須」と考えるのではなく、実際のブラウザがレスポンスをどのように扱うかを確認する必要があるということも分かった。

参考資料#

今回使用したGithubコード群

• RFC 6266 - Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP)
• RFC 8187 - Indicating Character Encoding and Language for HTTP Header Field Parameters
• MDN - Content-Disposition header
• Node.js v24 HTTP API Documentation