Web アプリケーションのファイルアップロードの最適化
アップロードの所要時間には、ファイルの前処理、転送、失われたリクエストの再試行、サーバーでの検証待ちが含まれます。この DevTip では、処理に制限を設けた画像前処理用のワーカーと、ブラウザーでの再開可能なアップロードを実装し、代替 UI として Uppy も紹介します。圧縮設定の選択や同時実行数の増加に先立ち、実際のデバイスとネットワークで各段階を測定してください。
これらの例は、以下のゲートウェイ契約を備えた既存のセッションベースのアプリケーションに組み込みます。セットアップとビルドは、そのアプリケーションの Yarn 4 プロジェクトルートで実行してください。package.json と public/ ディレクトリが必要です。コマンドは依存関係を更新し、指定したビルド済みアセットを置き換えますが、アプリケーションサーバーの作成や起動は行いません。Node 26.11.1 と Yarn 4.18.1 はビルドを検証したバージョンであり、ブラウザーアップロード自体の最小要件ではありません。Yarn はインストールガイドに従って別途インストールしてください。ブラウザーにはモジュールワーカー、createImageBitmap、OffscreenCanvas、AbortSignal.any()/timeout() が必要です。
ファイルアップロードでよくある課題
大きなファイルはメモリーを使い果たすことがあり、低速なネットワークはタイムアウトを招くことがあります。また、通信が中断すると、ブラウザーではリクエストが成功したか判断できない場合があります。有用な UI は、転送済みバイト数とサーバーによる受け入れを区別します。明らかに不適切なファイルをブラウザーが先に拒否する場合でも、セキュリティには、認証に基づく所有権確認とサーバーでの検証が必要です。
ファイルアップロードのパフォーマンス最適化のベストプラクティス
1. チャンク化したアップロードの利用
識別情報のないファイル断片を送信するのではなく、明示的なオフセットを持つ再開可能なプロトコルを使用してください。以下の tus 実装では、1 MiB のチャンクと回数を制限した再試行を使用します。これにより再転送のサイズは抑えられますが、どの接続でもスループットが向上するとは限りません。回復できない HTTP エラーが発生すると、最後のバイトがサーバーに届いた後のエラーも含め、処理は失敗します。
2. クライアント側の圧縮の実装
画像のリサイズは、CPU、画質、メタデータとの引き換えにバイト数を削減できます。以下の任意で使用するワーカーは、10 MiB 以下の JPEG または PNG ファイルを受け付けます。デコード後の画像を 16 百万ピクセル以下に制限し、両辺を 1024 × 1024 に収め、JPEG を生成します。透明部分は白になり、入力のメタデータはコピーされません。JPEG エンコーダーが解像度などの独自のメタデータを追加する場合はあります。ブラウザーの色変換により、CMYK JPEG を含む画像の色が変わる場合があります。結果を確認し、その変化を許容できない場合は元のファイルを保持してください。寸法が判明する前にデコードでメモリーが確保される場合があります。これは一般的なユーザー写真向けに制限を設けた便利な処理であり、悪意ある画像によるデコーダーへの攻撃を防ぐものではありません。
また、ブラウザーでデコードできても、破損した入力が完全であることの証明にはなりません。前処理後の JPEG にも、サーバー側のコンテンツ検証が必要です。前処理の制限時間は 30 秒です。低速なデバイスでは、条件を満たす画像でもタイムアウトする場合があります。
image-worker.js を作成します。
self.onmessage = async ({ data: file }) => {
let bitmap
try {
if (
!(file instanceof Blob) ||
file.size === 0 ||
file.size > 10 * 1024 * 1024 ||
!['image/jpeg', 'image/png'].includes(file.type)
) {
throw new Error('Unsupported image')
}
bitmap = await createImageBitmap(file)
if (bitmap.width * bitmap.height > 16_000_000) throw new Error('Image too large')
const scale = Math.min(1, 1024 / bitmap.width, 1024 / bitmap.height)
const width = Math.max(1, Math.round(bitmap.width * scale))
const height = Math.max(1, Math.round(bitmap.height * scale))
const canvas = new OffscreenCanvas(width, height)
const context = canvas.getContext('2d')
if (!context) throw new Error('Canvas unavailable')
context.fillStyle = 'white'
context.fillRect(0, 0, width, height)
context.drawImage(bitmap, 0, 0, width, height)
const blob = await canvas.convertToBlob({ type: 'image/jpeg', quality: 0.8 })
if (blob.type !== 'image/jpeg' || blob.size === 0) throw new Error('Encoding failed')
self.postMessage({ blob })
} catch {
self.postMessage({ error: 'Image preparation failed.' })
} finally {
bitmap?.close()
}
}
3. バックグラウンド処理への Web Workers の利用
ここでは、ワーカーをデコードとエンコードに使用します。Fetch と Blob の分割には、リクエストごとのワーカーは必要ありません。この prepare-image.js ラッパーは、成功、実行時エラー、メッセージのデコードエラー、キャンセル、タイムアウト、または postMessage の失敗時に、使用する単一のワーカーを終了します。
export function prepareImage(file, signal) {
signal.throwIfAborted()
return new Promise((resolve, reject) => {
const worker = new Worker(new URL('./image-worker.js', import.meta.url), { type: 'module' })
let settled = false
let timer
const finish = (error, blob) => {
if (settled) return
settled = true
clearTimeout(timer)
signal.removeEventListener('abort', abort)
worker.terminate()
if (error) reject(error)
else resolve(new File([blob], 'upload.jpg', { type: 'image/jpeg' }))
}
const abort = () => finish(new Error('Image preparation canceled.'))
signal.addEventListener('abort', abort, { once: true })
timer = setTimeout(() => finish(new Error('Image preparation timed out.')), 30_000)
worker.onerror = () => finish(new Error('Image worker failed.'))
worker.onmessageerror = () => finish(new Error('Invalid worker message.'))
worker.onmessage = ({ data }) => {
if (
!(data?.blob instanceof Blob) ||
data.blob.size === 0 ||
data.blob.type !== 'image/jpeg'
) {
finish(new Error('Image preparation failed.'))
return
}
finish(null, data.blob)
}
try {
worker.postMessage(file)
} catch {
finish(new Error('Could not start image preparation.'))
}
})
}
プラットフォームのドキュメントの OffscreenCanvas.convertToBlob と Worker.terminate を参照してください。
ファイルアップロード時のセキュリティの確保
1. ファイルの種類とサイズの検証
アップロード関数は 10 MiB 以下のファイルを受け付けます。クライアントからの MIME タイプ、名前、サイズは、信頼できないメタデータです。サーバーでは、アップロードを利用可能にする前に、バイト数を独立して制限し、対応するコンテンツを検出して、セキュリティスキャンやデコードのポリシーを適用する必要があります。
2. 安全なファイルストレージの利用
以下のブラウザーの例には、/api/tus/files/ に tus エンドポイントを備えた、認証付きの既存の同一オリジンアプリケーションが必要です。これはクライアント向けのチュートリアルであり、サーバーの構築は行いません。保守されている Node.js tus サーバーは、プロトコルとストレージの実装を提供します。アプリケーションのゲートウェイでは、セッションと公開ポリシーを実装する必要があります。変更操作時にはセッションと X-CSRF-TOKEN を検証し、すべての tus リクエストで X-Upload-Owner をセッションと照合するように設定してください。合計 10 MiB、チャンク 1 MiB、ユーザーごとのストレージとレートの制限、有効期限、非公開のステージングを必須にしてください。作成、HEAD、PATCH、終了リクエストのいずれでも所有権を確認してください。リダイレクトを拒否し、/api/tus/files/ 配下の同一オリジンの Location URL だけを返してください。
tus が完了を報告した後、POST /api/upload-publications は {uploadUrl} を受け付けます。サーバーは、その URL を自身が所有するアップロードレコードに対してのみ解決し、任意の URL を取得してはいけません。完全性とコンテンツを検証した後、アトミックに一度だけ公開します。重複リクエストには、HTTP 200 または 201 で同じ受領証を返します。成功以外の応答や 202 は、公開の確認にはなりません。不透明で空でない受領証 ID を含む {id} を返してください。ダウンロードへのアクセスには、リクエストしたユーザーの認可が別途必要です。ランダムなファイル名だけではアクセス制御になりません。
tus による再開可能なアップロードの実装
プロトコル名は tus です。ブラウザープロジェクトに、検証済みのクライアントバージョンをインストールしてください。
(command -v node >/dev/null && command -v yarn >/dev/null &&
yarn add --exact tus-js-client@4.3.1 &&
yarn add --dev --exact esbuild@0.28.2)
upload.js を作成します。認証済みページから、現在の所有者 ID と
CSRF トークンを渡してください。どちらも Transloadit の Auth Secret ではありません。この関数は、同じページセッション内で中断を再試行します。新たに選択したファイルを、名前だけに基づいて以前のアップロードに自動で関連付けることはありません。中止または失敗したアップロードはサーバー上で期限切れになり、新しい呼び出しは新しいアップロードを作成します。
import { Upload } from 'tus-js-client'
export async function uploadFile(file, { owner, csrf, signal, onProgress }) {
signal.throwIfAborted()
if (
!(file instanceof Blob) ||
file.size === 0 ||
file.size > 10 * 1024 * 1024 ||
!owner ||
!csrf
) {
throw new Error('Choose a file between 1 byte and 10 MiB while signed in.')
}
const headers = { 'X-CSRF-TOKEN': csrf, 'X-Upload-Owner': owner }
const uploadUrl = await new Promise((resolve, reject) => {
let settled = false
let timer
const finish = (error, url) => {
if (settled) return
settled = true
clearTimeout(timer)
signal.removeEventListener('abort', abort)
if (error) {
void upload.abort().catch(() => {})
reject(error)
} else resolve(url)
}
const abort = () => finish(new Error('Upload canceled.'))
const upload = new Upload(file, {
endpoint: '/api/tus/files/',
headers,
httpStack: {
getName() { return 'SameOriginFetch' },
createRequest(method, url) {
const controller = new AbortController()
const requestHeaders = new Headers()
return {
getMethod() { return method },
getURL() { return url },
getUnderlyingObject() { return controller },
setHeader(name, value) { requestHeaders.set(name, value) },
getHeader(name) { return requestHeaders.get(name) },
setProgressHandler() {},
async abort() { controller.abort() },
async send(body) {
const response = await fetch(url, {
method, body, headers: requestHeaders,
credentials: 'same-origin', redirect: 'error', signal: controller.signal,
})
const text = response.ok ? await response.text() : ''
return {
getStatus() { return response.status },
getHeader(name) { return response.headers.get(name) },
getBody() { return text },
getUnderlyingObject() { return response },
}
},
}
},
},
chunkSize: 1024 * 1024,
storeFingerprintForResuming: false,
retryDelays: [0, 1000, 3000],
onShouldRetry(error) {
const status = error.originalResponse?.getStatus() ?? 0
return status === 0 || status === 409 || status === 423 || status === 429 || status >= 500
},
onBeforeRequest(request) {
const url = new URL(request.getURL(), location.href)
if (url.origin !== location.origin || !url.pathname.startsWith('/api/tus/files/')) {
throw new Error('Unexpected upload URL')
}
},
onProgress(loaded, total) {
try {
onProgress(Math.min(99, Math.floor((100 * loaded) / total)))
} catch {
finish(new Error('Progress display failed.'))
}
},
onError() {
finish(new Error('Upload failed.'))
},
onSuccess() {
if (!upload.url) finish(new Error('Missing upload URL.'))
else finish(null, upload.url)
},
})
signal.addEventListener('abort', abort, { once: true })
timer = setTimeout(() => finish(new Error('Upload timed out.')), 120_000)
try {
upload.start()
} catch {
finish(new Error('Could not start upload.'))
}
})
signal.throwIfAborted()
const response = await fetch('/api/upload-publications', {
method: 'POST',
credentials: 'same-origin',
redirect: 'error',
headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({ uploadUrl }),
signal: AbortSignal.any([signal, AbortSignal.timeout(30_000)]),
})
if (!response.ok || ![200, 201].includes(response.status)) {
throw new Error(`Publication not confirmed (HTTP ${response.status}).`)
}
const receipt = await response.json()
if (typeof receipt.id !== 'string' || !receipt.id) throw new Error('Invalid publication receipt.')
onProgress(100)
return receipt.id
}
ここでは実際の tus-js-client のオプションとコールバックを使用しています。小さな Fetch トランスポートでクライアントの HTTP スタックインターフェースを実装し、リダイレクトをたどる前に拒否します。進捗は送信中のバイト数ではなく、tus のチャンク境界で更新されます。応答が失われると、tus が確定済みオフセットを照合する前にブラウザーがリクエストを再送する場合があります。サーバーは古いオフセットを拒否し、重複するバイトを追記しないようにする必要があります。制限時間の二分間は、再試行を含む転送全体に適用されます。公開の応答が失われた場合、結果は不確定です。別のアップロードを開始する前に、サーバーのアップロード一覧を確認してください。低速な接続では、10 MiB 未満でもこの制限時間に達する場合があります。最終的な公開には、別途 30 秒の制限時間があります。キャンセルはクライアントの処理を停止しますが、サーバーがアップロードを削除した、または公開を見合わせたことの証明にはなりません。放棄されたステージングはサーバー側で期限切れにしてください。
ページ全体に組み込むには、セッションベースのページから、エスケープ済みの
data-upload-owner 属性と data-csrf 属性を
<html> に出力し、次を追加します。
<label>File <input id="file" type="file" /></label>
<label><input id="resize" type="checkbox" /> Prepare JPEG or PNG as JPEG</label>
<button id="upload" type="button">Upload</button>
<button id="cancel" type="button">Cancel</button>
<progress id="progress" aria-label="Upload progress" max="100" value="0"></progress>
<p id="status" role="status"></p>
<script type="module" src="/main.js"></script>
main.js を作成します。
import { prepareImage } from './prepare-image.js'
import { uploadFile } from './upload.js'
const input = document.getElementById('file')
const button = document.getElementById('upload')
const status = document.getElementById('status')
const resize = document.getElementById('resize')
let controller = null
button.onclick = async () => {
if (controller || !input.files?.[0]) return
controller = new AbortController()
button.disabled = true
input.disabled = true
resize.disabled = true
document.getElementById('progress').value = 0
status.textContent = 'Preparing upload…'
try {
let file = input.files[0]
if (resize.checked) {
file = await prepareImage(file, controller.signal)
}
await uploadFile(file, {
owner: document.documentElement.dataset.uploadOwner,
csrf: document.documentElement.dataset.csrf,
signal: controller.signal,
onProgress(value) {
document.getElementById('progress').value = value
},
})
status.textContent = 'Upload published.'
} catch {
status.textContent = 'Upload failed or canceled. Check your uploads before retrying.'
} finally {
controller = null
button.disabled = false
input.disabled = false
resize.disabled = false
}
}
document.getElementById('cancel').onclick = () => controller?.abort()
メインエントリーをバンドルし、同じ HTTPS オリジンの同じ場所でワーカーを配信します。
(command -v node >/dev/null && command -v yarn >/dev/null && command -v cp >/dev/null &&
yarn esbuild main.js --bundle --format=esm --tsconfig-raw='{}' --outfile=public/main.js &&
cp image-worker.js public/image-worker.js)
Uppy によるシームレスなユーザー体験
Uppy は選択、制限、進捗、キャンセルの UI を提供します。このゲートウェイでは、Uppy のカスタムアップローダーインターフェースから、同じ
uploadFile 関数を呼び出します。これにより公開も成功条件に含まれ、制限時間、認証ヘッダー、エラー処理も共通になります。これは代替のエントリーポイントであり、前のページと並べて配置する追加アップローダーではありません。
互換性のあるパッケージをインストールします。
(command -v node >/dev/null && command -v yarn >/dev/null &&
yarn add --exact @uppy/core@6.2.0 @uppy/dashboard@6.0.1)
uppy-main.js を作成し、<div id="drag-drop-area"></div> と同じセッション属性を持つページにマウントします。この UI を削除するときは、アプリケーションが返されたクリーンアップ関数を呼び出す必要があります。
import Uppy from '@uppy/core'
import Dashboard from '@uppy/dashboard'
import '@uppy/core/css/style.min.css'
import '@uppy/dashboard/css/style.min.css'
import { uploadFile } from './upload.js'
export function mountUploader() {
const uppy = new Uppy({
restrictions: { maxNumberOfFiles: 1, maxFileSize: 10 * 1024 * 1024, minFileSize: 1 },
}).use(Dashboard, { inline: true, target: '#drag-drop-area' })
let active = null
let destroyed = false
const cancel = () => {
const previous = active
active = null
previous?.controller.abort()
}
uppy.on('cancel-all', cancel)
uppy.on('file-removed', (file) => {
if (active?.fileId === file.id) cancel()
})
uppy.addUploader(async (ids) => {
if (active) throw new Error('An upload is already running.')
const file = uppy.getFile(ids[0])
if (!file || !(file.data instanceof Blob)) throw new Error('Select a local file.')
const operation = { fileId: file.id, controller: new AbortController() }
const uploadStarted = Date.now()
active = operation
const current = () => !destroyed && active === operation && Boolean(uppy.getFile(file.id))
uppy.emit('upload-start', [file])
try {
const id = await uploadFile(file.data, {
owner: document.documentElement.dataset.uploadOwner,
csrf: document.documentElement.dataset.csrf,
signal: operation.controller.signal,
onProgress(value) {
if (!current()) return
uppy.emit('upload-progress', file, {
uploadStarted,
bytesUploaded: Math.floor((file.data.size * value) / 100),
bytesTotal: file.data.size,
})
},
})
if (current()) uppy.emit('upload-success', file, { status: 200, body: { id } })
} catch {
if (!current()) return
uppy.emit('upload-error', file, new Error('Upload not confirmed. Check your uploads.'))
throw new Error('Upload not confirmed.')
} finally {
if (active === operation) active = null
}
})
return () => {
destroyed = true
cancel()
uppy.destroy()
}
}
let cleanup = mountUploader()
window.addEventListener('pagehide', () => cleanup())
window.addEventListener('pageshow', (event) => {
if (event.persisted) cleanup = mountUploader()
})
基本ページのコントロールとスクリプトの代わりに、このマークアップを使用します。<html> には同じセッション属性を設定してください。
<link rel="stylesheet" href="/uppy-main.css" />
<div id="drag-drop-area"></div>
<script type="module" src="/uppy-main.js"></script>
代替エントリーポイントをビルドします。
(command -v node >/dev/null && command -v yarn >/dev/null &&
yarn esbuild uppy-main.js --bundle --format=esm --tsconfig-raw='{}' --outfile=public/uppy-main.js)
キャンセル時には、別のファイルを受け付ける前に現在の処理を無効化します。そのため、遅れて到着したコールバックが次の処理を失敗扱いにしたり、そのキャンセルハンドルを消去したりすることはありません。pagehide 時には、この実装は Dashboard を破棄し、実行中のクライアント処理をキャンセルします。永続化されたページの復元時には、空の Dashboard をマウントします。戻った後にファイルを再選択してください。リモートプロバイダーからのアップロードには、認証付きの Companion 連携が別途必要です。この例はローカルの Blob のみを受け付けます。Uppy のアップローダー API を参照してください。
公開結果の確認
基本ページでファイルを選択し、必要に応じて画像の前処理を有効にして、Upload を選択してください。ページは有効なサーバー受領証を待ってから Upload published. を表示します。
Uppy で対応する状態は Complete です。202 応答、検証の失敗、タイムアウトの場合、すべてのバイトを送信済みでもアップロードは未確認のままです。公開結果が不確定な場合は、再試行する前に認証済みのアップロード一覧を確認してください。新しい呼び出しは新しいステージングを作成します。
前処理していないファイルでは、アプリケーションの認可された検査ツールを使い、保存されたバイト数と SHA-256 を選択したファイルと比較してください。前処理した画像では、出力された JPEG を確認してください。縦横とも 1024 以下で、丸め誤差の範囲でアスペクト比が維持され、透明部分の背景が白になっていることを確認します。小さな PNG は、リサイズと JPEG エンコードによってサイズが増える場合があります。前処理をデフォルトで有効にする前に、処理後のサイズと見た目の画質を測定してください。
関連リソース
よくある質問への回答
アップロードを確認するにはどうすればよいですか? 転送したバイト数だけでは不十分です。検証と公開の後に、認証済みのサーバー受領証を確認してください。プロバイダー固有のマルウェア解析は別の連携であり、汎用的に使えるアップロード検証用の CLI コマンドはありません。
制限のないファイルアップロードとは何ですか? 十分な制約なしにコンテンツを受け付けるアップロードエンドポイントのことです。危険なファイルの保存や実行を許すおそれがあります。サーバーで検証し、ストレージを実行可能な Web コンテンツから分離してください。
ファイルアップロードに対応する HTML フォームのエンコーディングは何ですか?従来のフォームでは、名前付きのファイル入力とともに method="post" と
enctype="multipart/form-data" を使用します。ブラウザーで Fetch または Axios を使って
FormData を送信する場合は、multipart の境界をブラウザーに設定させてください。ヘッダーを自分で組み立てないでください。
