開発者向け HTML ファイルアップロードフォーム作成ガイド
HTML でファイルをアップロードするには、method="post" と
enctype="multipart/form-data" を指定したフォーム内に名前付きのファイル入力を配置し、フォームの action を処理するサーバーを用意します。このチュートリアルでは、これらを組み合わせます。ブラウザーの JavaScript を使わずに単一または複数のファイルを送信し、受信サーバーが返すファイル名、バイト数、SHA-256 ハッシュを確認します。
HTML の基本的なファイルアップロードフォームの準備
Node.js 24 以降、ブラウザー、および Linux、macOS、WSL 上の Bash などの POSIX シェルが必要です。受信サーバーは Node の組み込み API を使うため、パッケージのインストールは不要です。Node は型の除去(type stripping)によって、この TypeScript を直接実行できます。サンプルは Linux 上で Node.js 24.15.0、26.5.0、26.8.1 と Chromium 145、152 を使ってテストしています。
実験用のディレクトリで、次を実行します。
mkdir html-upload-demo &&
cd html-upload-demo &&
touch index.html server.ts
既存のディレクトリがある場合、このコマンドは失敗します。失敗したら以降の手順には進まず、別のディレクトリ名を選ぶか、エラーを解消してください。作成したファイルに、次のふたつのサンプルを貼り付けます。サーバーはアップロードされたデータをメモリ内でのみ調べます。アップロードされたファイルを作成したり上書きしたりすることはなく、同じファイルを再送信すると、単に別の受信記録が生成されます。
次のページ全体を index.html として保存します。
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>HTML file upload demo</title>
</head>
<body>
<main>
<h1>Upload files</h1>
<form action="/upload" method="post" enctype="multipart/form-data">
<p>
<label for="file-upload">Choose files (required)</label>
<input
type="file"
id="file-upload"
name="files"
multiple
required
aria-describedby="file-help"
/>
</p>
<p id="file-help">Choose up to three files, at most 1 MiB each. Nothing is saved.</p>
<button type="submit">Upload files</button>
</form>
</main>
</body>
</html>
フォームの各属性には、それぞれ異なる役割があります。
| 属性 | この例での役割 |
|---|---|
action="/upload" | このページを配信するサーバーの /upload ルートに送信します。 |
method="post" | HTTP リクエスト本文にフォームデータを入れて送信します。 |
enctype="multipart/form-data" | ファイルの内容を、本文内の個別のパートとしてエンコードします。 |
name="files" | 受信サーバーが取得できるよう、アップロードする各パートに名前を付けます。 |
id="file-upload" | 入力要素とラベルを関連付けます。送信するフィールドの名前ではありません。 |
multiple | ファイル選択で複数のファイルを選べるようにします。 |
required | 送信前にブラウザーがファイルの選択を求めるようにします。 |
multipart の境界とリクエストヘッダーはブラウザーが生成します。エンコードの仕組みは、MDN のフォームデータの送信ガイドで解説されています。name がない入力要素は、id があり、選択したファイル名が表示されていても、送信データには含まれません。HTML 標準のフォームエントリーの規則を参照してください。
ローカルの multipart 受信サーバーの追加
次を server.ts として保存します。ページを配信し、それぞれ 1 MiB までのファイルを最大三つ受け付けます。これとは別に、解析前にバッファリングするリクエスト本文には、multipart ヘッダーを含めて
4 MiB の上限を設けています。これらはデモ用の小さな上限です。バッファリングと解析には、未加工の本文サイズを超えるメモリも必要です。
import { createHash } from 'node:crypto'
import { readFile } from 'node:fs/promises'
import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
const MAX_FILES = 3
const MAX_FILE_BYTES = 1024 * 1024
const MAX_REQUEST_BYTES = 4 * 1024 * 1024
const page = await readFile(new URL('./index.html', import.meta.url))
function reply(response: ServerResponse, status: number, message: string): void {
response.writeHead(status, {
'Content-Type': 'text/plain; charset=utf-8',
'Cache-Control': 'no-store',
'X-Content-Type-Options': 'nosniff',
})
response.end(`${message}\n\nUse Back to choose files again. Nothing was saved.\n`)
}
async function handle(request: IncomingMessage, response: ServerResponse): Promise<void> {
if (request.method === 'GET' && request.url === '/') {
response.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
response.end(page)
return
}
if (request.method === 'GET' && request.url === '/favicon.ico') {
response.writeHead(204).end()
return
}
if (request.method !== 'POST' || request.url !== '/upload') {
reply(response, 404, 'Route not found. Open the URL printed in the terminal.')
return
}
const contentType = request.headers['content-type'] ?? ''
if (!contentType.toLowerCase().startsWith('multipart/form-data;')) {
request.resume()
reply(response, 415, 'Expected multipart/form-data. Check the form enctype.')
return
}
const chunks: Buffer[] = []
let bytes = 0
// Keep the connection alive long enough to return readable size-limit feedback.
for await (const chunk of request.iterator({ destroyOnReturn: false })) {
if (!Buffer.isBuffer(chunk)) throw new Error('Expected request bytes')
bytes += chunk.length
if (bytes > MAX_REQUEST_BYTES) {
request.resume()
reply(response, 413, 'Request exceeds 4 MiB. Choose smaller files.')
return
}
chunks.push(chunk)
}
let form: FormData
try {
form = await new Request('http://localhost/upload', {
method: 'POST',
headers: { 'Content-Type': contentType },
body: Buffer.concat(chunks),
}).formData()
} catch {
reply(response, 400, 'Could not read the multipart form. Check its encoding.')
return
}
const files = form.getAll('files')
if (files.length === 0) {
reply(response, 400, 'Choose at least one file in the files field.')
return
}
if (files.length > MAX_FILES) {
reply(response, 400, 'Choose at most three files.')
return
}
const receipts = []
for (const file of files) {
if (!(file instanceof File) || file.name === '') {
reply(response, 400, 'Choose at least one file in the files field.')
return
}
if (file.size > MAX_FILE_BYTES) {
reply(response, 413, 'Each file must be at most 1 MiB. Choose smaller files.')
return
}
receipts.push({
field: 'files',
name: file.name,
bytes: file.size,
sha256: createHash('sha256').update(Buffer.from(await file.arrayBuffer())).digest('hex'),
})
}
reply(response, 200, `Received ${files.length} file(s).\n${JSON.stringify(receipts, null, 2)}`)
}
const server = createServer((request, response) => {
void handle(request, response).catch(() => {
console.error('Upload handler failed.')
if (!response.headersSent) reply(response, 500, 'Could not process the upload. Try again.')
else response.destroy()
})
})
server.listen(0, '127.0.0.1', () => {
const address = server.address()
if (address && typeof address !== 'string') {
console.log(`Open http://127.0.0.1:${address.port}/`)
}
})
組み込みの Request APIは、収集した本文を
formData()で解析します。このオブジェクトを構築しても、別のネットワークリクエストが送信されることはありません。受信サーバーは getAll('files')を使い、その名前を持つすべてのパートを取得します。get('files') では最初のパートしか返されません。
ストリームの
destroyOnReturn: false オプションにより、本文が大きすぎる場合も、接続を破棄せずに読み取りループを抜けられます。受信サーバーは残りの入力を破棄し、HTTP 413 レスポンスを返します。
単一ファイルと複数ファイルのアップロード処理
同じ html-upload-demo ディレクトリで、受信サーバーを起動します。
node server.ts
ターミナルに表示された URL をそのまま開きます。サーバーは空いているポートを選び、127.0.0.1 でのみ待ち受けます。index.html をローカルファイルとして直接開いても、その /upload アクションはこの受信サーバーに接続されません。終了時は Ctrl+C でサーバーを停止します。どちらかのファイルを編集したら再起動してください。
ブラウザーで JavaScript を無効にして再読み込みし、小さなファイルをひとつ選びます。Upload files をクリックします。ブラウザーは /upload に移動し、Received 1 file(s). と、field、name、bytes、sha256 を含む受信記録を表示します。このレスポンスで、サーバーがバイト列を受け付けて調べたことを確認できます。ファイル選択欄にファイル名が表示されるだけでは、選択したことしか確認できません。
ブラウザーの「戻る」で戻り、ファイルをふたつ同時に選んで再送信します。Received 2 file(s). とふたつの受信記録が表示されるはずです。空白や非 ASCII 文字を含むファイル名も試してください。受信記録をローカルファイルと照合するには、デモのディレクトリで次を実行します。-- の後のパスを、対象ファイルのパスに置き換えてください。
node --input-type=module -e 'import { readFile } from "node:fs/promises"; import { createHash } from "node:crypto"; const bytes = await readFile(process.argv[1]); console.log(bytes.length, createHash("sha256").update(bytes).digest("hex"))' -- '/path/to/your file.txt'
バイト数とハッシュの両方が一致するはずです。このコマンドはファイルを読み取るだけです。意図的に選択した空のファイルは有効で、バイト数はゼロと表示されます。ファイルを何も選択していない場合とは異なります。
multiple は選択できるファイル数を変更するもので、フィールド名を変更するものではありません。選択した各ファイルは files という名前で送信されます。HTML では files[] という角括弧の慣例は必須ではありません。この受信サーバーは、キーが文字どおり files であることを想定しています。別のバックエンドが files[] を想定する場合は、双方でその名前を正確に使う必要があります。ファイルをひとつしか選択できないようにするには、multiple を省きます。ただし、これはブラウザーのコントロールを変更するだけです。アプリケーションでファイルをひとつに制限する必要がある場合は、サーバー側でも制限してください。
クライアント側の検証の追加
何も選択せずに Upload files をクリックすると、ブラウザーが必須入力のメッセージを表示し、フォームのページにとどまります。クライアントはブラウザーの検証を回避できるため、受信サーバーも空のアップロードを HTTP 400 で拒否します。HTML には 1 MiB の上限を強制するファイルサイズ属性がないため、サイズ超過のファイルを選ぶと受信サーバーまで送信され、エラーページが返されます。
このデモはどの種類のファイルも受け付け、バイト列を調べるだけです。画像やドキュメントの選択を誘導するには、入力要素に accept=".jpg,.jpeg,.png,.pdf" を追加できます。MDN のファイル入力のドキュメントにあるとおり、accept はファイル選択のヒントであり、内容の検証ではありません。これを追加しても、受信サーバーが種類を検証するようにはなりません。ファイル名、拡張子、送信された MIME タイプだけでは、ファイルの安全性は判断できません。
サンプルを応用する前に、次の失敗例を試してください。
| 送信内容 | 期待される結果 |
|---|---|
| ファイル未選択 | ブラウザーがファイルの選択を求めます。空のリクエストを直接送ると HTTP 400 が返ります。 |
| 小さなファイルを四つ | HTTP 400:「Choose at most three files.」 |
| 1 MiB を超えるファイルをひとつ | HTTP 413 とサイズ上限のメッセージが返ります。 |
| リクエスト全体が 4 MiB 超 | multipart の解析前に HTTP 413 が返ります。 |
file または files[] という名前のファイルフィールド | 受信サーバーが files を見つけられないため、HTTP 400 が返ります。 |
エラーが出たら、ブラウザーの「戻る」で戻って有効なファイルを選択します。成功レスポンスは、その送信全体に適用されます。成功したリクエストでも拒否されたリクエストでも、何も保存されません。
ファイルアップロードボタンのカスタマイズ
標準ボタンのラベル、選択ファイルの表示、キーボード操作を維持したまま、スタイルを変更できます。index.html の <head> 内に次を追加し、サーバーを再起動します。
<style>
input[type='file']::file-selector-button {
font: inherit;
padding: 0.5rem 0.75rem;
margin-inline-end: 0.75rem;
cursor: pointer;
}
</style>
::file-selector-button 擬似要素は、入力要素内のボタンを対象にします。Tab キーでラベル付きのファイル選択欄に移動し、Space キーで開きます。続いて Tab キーで Upload files に移動し、Enter キーで送信します。入力要素は表示したままにし、フォーカス表示も維持してください。name="files" とフォーム内の配置によって、選択したファイルは引き続き受信サーバーに関連付けられます。
セキュリティ上の注意点
この受信サーバーはローカルでのみ使用してください。任意の内容を受け付け、リクエストごとにメモリを使用しますが、ログイン、永続ストレージ、マルウェアスキャンの機能はありません。ファイル名はプレーンテキストのレスポンス内に JSON として表示され、ファイルシステムのパスとして使われることはありません。ハッシュで確認できるのは受信したバイト列であり、その形式や安全性を検証するものではありません。
認証を備えたアプリケーションにストレージを追加する際は、サーバー境界で認可、リクエストの上限、内容の検証、CSRF 対策を定義してください。このセキュリティ対策については、別の安全な AJAX アップロードガイドで解説しています。
必要に応じた進捗表示やドラッグ&ドロップの追加
ページを移動せずにアップロードの進捗を表示するインターフェイスを作るには、カスタム JavaScript アップローダーに進んでください。対応する受信サーバーとともに、ドラッグ&ドロップ、再試行、進捗表示を解説しています。アプリケーションですでに Bootstrap を使っている場合は、Bootstrap ファイルアップロードチュートリアルで、そのスタイル設定方法を確認してください。
