Uppy、XHRUpload、Express によるファイルアップロード
Uppy の Dashboard でファイルを選択し、XHRUpload でマルチパートエンドポイントに送信します。このチュートリアルでは、ローカルのブラウザーからサーバーへの完全な実装例を構築します。進捗表示と再試行コントロールを備えたファイル選択画面と、アップロードごとにバイト数と SHA-256 を返す Express の受信サーバーを用意します。
アップロードの仕様の選択
Dashboard がインターフェイスを提供し、XHRUpload がファイルごとにマルチパート POST を一回送信します。受信側はフィールド
file を受け取り、ファイル全体を読み取ってから JSON を返します。Uppy とは別に、手書きの XMLHttpRequest を併用することはありません。
これはローカル転送のデモです。受信側はリクエストの処理中に各ファイルをメモリに保持し、ハッシュを計算してから破棄します。ファイルの保存、ダウンロードリンクの返却、内容の検査は行いません。成功レスポンスは、受信側がバイト列を読み取ったことを示すもので、永続的に保存したことを示すものではありません。
プロジェクトの作成
Linux 上の Bash と、保守されている Node.js 24 または 26 の LTS リリースを使用します。この例は 2026年11月7日に Node.js 24.22.2 と 26.13.0、Corepack 0.34.5、Yarn 4.12.0、Chromium 145 で検証しました。Node.js 24 には Corepack が同梱されていますが、Node.js 26 では
Corepack の別途インストールが必要です。開始前に node --version と corepack --version を確認してください。以下のセットアップでは、デモのパッケージマネージャーを設定した後、Yarn が
4.12.0 を報告することを確認します。Node は組み込みの TypeScript 型除去機能を使って
server.ts を実行し、esbuild がブラウザー用コードをバンドルします。
新規インストールでは、いずれかの保守中の LTS 系列で最新のパッチリリースを使用してください。2026年9月28日版のこのチュートリアルでは Node.js 24.15.0 と 26.8.1 を使用していましたが、これらは 10月のセキュリティ更新より前のバージョンです。以下のパッケージのバージョン固定は、検証済みの例の依存関係を維持しています。
新しい uppy-xhr-demo フォルダーを作成したいディレクトリで、以下を貼り付けてください。Yarn Plug’n’Play プロジェクトの外で実行します。このプロジェクトが node_modules を使っていても、esbuild は祖先ディレクトリの PnP マニフェストを検出することがあります。セットアップではファイル作成前にその有無を確認します。丸括弧により、シェルは元のディレクトリにとどまります。デモ用フォルダーがすでに存在する場合、変更せずに停止します。新しい場所を選んでください。インストールに失敗した場合は、続行せずに問題を解決してください。
(
node --input-type=module -e '
import { existsSync } from "node:fs"
import { dirname, join } from "node:path"
for (let directory = process.cwd();; directory = dirname(directory)) {
for (const name of [".pnp.cjs", ".pnp.js"]) {
if (existsSync(join(directory, name))) {
console.error("Choose a directory outside a Yarn PnP project.")
process.exit(1)
}
}
if (directory === dirname(directory)) break
}
' &&
mkdir uppy-xhr-demo &&
cd uppy-xhr-demo &&
printf '%s\n' '{"private":true,"type":"module","packageManager":"yarn@4.12.0"}' > package.json &&
printf '%s\n' 'nodeLinker: node-modules' 'ignorePath: true' > .yarnrc.yml &&
touch yarn.lock &&
corepack yarn --version &&
corepack yarn add --exact @uppy/core@6.0.2 @uppy/dashboard@6.0.0 @uppy/xhr-upload@6.0.0 express@5.2.1 multer@2.4.0 esbuild@0.27.0 &&
mkdir public
)
空のロックファイルによって、独立した Yarn プロジェクトになります。ignorePath 設定は、祖先ディレクトリの
yarnPath が選択した Yarn バージョンを置き換えるのを防ぎます。検証済みの組み合わせを再現してインストールできるよう、生成された
yarn.lock を保持してください。ローカルの package.json は、親が CommonJS プロジェクトでも
ES modules の使用を確立します。Yarn の node-modules リンカーにより、通常の Node でサーバーのインポートを解決できます。
以下の三つのファイルを uppy-xhr-demo 内に保存してください。
受信サーバーの追加
以下を server.ts として保存してください。Multer はマルチパートボディを解析し、受信中にリクエストの制限を適用します。受信側は、リクエストごとに最大 2 MiB のファイルを一つ受け付け、追加のテキストフィールドは受け付けません。MIME チェックで確認するのは送信側の申告のみです。バイト列が有効な画像や PDF であることを証明するものではありません。
Node のデフォルトのリクエストタイムアウトでは、リクエストの受信に五分間が許容され、定期的に確認されます。アップロードが十分に遅い場合は、ファイルが 2 MiB 未満でも HTTP 408 が返ることがあります。
import { createHash } from 'node:crypto'
import { join } from 'node:path'
import express from 'express'
import multer from 'multer'
const app = express()
const receive = multer({
storage: multer.memoryStorage(),
limits: { fileSize: 2 * 1024 * 1024, files: 1, fields: 0 },
}).single('file')
const allowedTypes = new Set(['image/jpeg', 'image/png', 'application/pdf'])
app.use(express.static(join(import.meta.dirname, 'public')))
app.post('/upload', (req, res) => {
receive(req, res, (error: unknown) => {
if (error) {
const tooLarge = error instanceof multer.MulterError && error.code === 'LIMIT_FILE_SIZE'
res.status(tooLarge ? 413 : 400).json({ error: 'Upload rejected.' })
return
}
const file = req.file
if (!file) {
res.status(400).json({ error: 'Expected one file in the file field.' })
return
}
if (!allowedTypes.has(file.mimetype)) {
res.status(415).json({ error: 'Expected a JPEG, PNG, or PDF MIME type.' })
return
}
res.json({
bytes: file.size,
sha256: createHash('sha256').update(file.buffer).digest('hex'),
})
})
})
const port = Number(process.env.PORT ?? 0)
if (!Number.isInteger(port) || port < 0 || port > 65535) {
throw new Error('PORT must be an integer from 0 to 65535.')
}
const server = app.listen(port, '127.0.0.1', (error?: Error) => {
if (error) {
console.error(`Cannot start the upload server: ${error.message}`)
process.exitCode = 1
return
}
const address = server.address()
if (!address || typeof address === 'string') throw new Error('Missing listening address.')
console.log(`Open http://127.0.0.1:${address.port}`)
})
ポート番号ゼロを指定すると、OS に空きポートを要求します。必要に応じて
PORT に固定ポートを設定できます。コールバックで Express 5 の起動エラーを処理するため、ポートが使用中の場合は、準備完了と誤解させるアドレスを表示せず、異常終了します。
ページとアップローダーの追加
以下を public/index.html として保存してください。
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Uppy upload demo</title>
<link rel="icon" href="data:," />
<link rel="stylesheet" href="/app.css" />
<style>
body { margin: 1rem; font-family: sans-serif; }
#receipts { overflow-wrap: anywhere; }
</style>
<script type="module" src="/app.js"></script>
</head>
<body>
<h1>Upload to the local receiver</h1>
<div id="drag-drop-area"></div>
<h2>Received by the server</h2>
<p>These receipts confirm transfer. Files are not saved.</p>
<ul id="receipts" aria-label="Server receipts" aria-live="polite"></ul>
</body>
</html>
以下を client.ts として保存してください。Dashboard には、選択エラー、アップロードの進捗、キャンセル、再試行コントロールがすでに備わっています。小さなイベントハンドラーで
textContent を使ってサーバーの受信確認を追加するため、ファイル名はテキストとして表示されます。
import Uppy from '@uppy/core'
import Dashboard from '@uppy/dashboard'
import XHRUpload from '@uppy/xhr-upload'
import '@uppy/core/css/style.min.css'
import '@uppy/dashboard/css/style.min.css'
const receipts = document.querySelector('#receipts')
if (!(receipts instanceof HTMLUListElement)) throw new Error('Missing receipt list.')
const uppy = new Uppy({
autoProceed: false,
allowMultipleUploadBatches: false,
restrictions: {
maxFileSize: 2 * 1024 * 1024,
maxNumberOfFiles: 5,
allowedFileTypes: ['image/jpeg', 'image/png', '.pdf'],
},
})
.use(Dashboard, {
inline: true,
target: '#drag-drop-area',
note: 'Up to five JPEG, PNG, or PDF files, each up to 2 MiB.',
})
.use(XHRUpload, {
endpoint: '/upload',
fieldName: 'file',
formData: true,
bundle: false,
allowedMetaFields: false,
limit: 2,
shouldRetry: () => false,
onAfterResponse(xhr) {
if (xhr.status === 413) throw new Error('Choose a file no larger than 2 MiB.')
if (xhr.status === 415) throw new Error('The server requires a JPEG, PNG, or PDF MIME type.')
if (xhr.status < 200 || xhr.status >= 300) {
throw new Error('The server rejected the upload. Check the endpoint before retrying.')
}
},
})
uppy.on('upload-success', (file, response) => {
if (!file) return
const item = document.createElement('li')
item.textContent = `${file.name}: ${JSON.stringify(response.body)}`
receipts.append(item)
})
fieldName は受信側の single('file') と一致します。allowedMetaFields: false は Uppy のデフォルトのメタデータフィールドを省略し、サーバーのフィールド数ゼロという制限に合わせます。Content-Type ヘッダーを手動で設定しないでください。マルチパートの境界はブラウザーが設定します。二つのファイルを同時に転送でき、残りのファイルは Uppy のキューで待機します。
ビルドとアップロードの試行
セットアップを実行したのと同じ親ディレクトリで、ブラウザー用バンドルをビルドし、サーバーを起動してください。
(
cd uppy-xhr-demo &&
corepack yarn exec esbuild client.ts --bundle --format=esm --outfile=public/app.js &&
node server.ts
)
esbuild は public/app.js と public/app.css の両方を出力します。CSS には HTML 内に専用のリンクが必要です。上記のページにはそのリンクが含まれています。再ビルドすると、この二つの生成ファイルが置き換わります。再ビルドの前に Ctrl+C でフォアグラウンドのサーバーを停止し、再起動後にページを再読み込みしてください。
サーバーが表示したアドレスをそのまま開いてください。browse files でファイルを選択し、Dashboard のアップロードボタンを押します。ファイルを一つ選択した場合、ボタンには
Upload 1 file と表示されます。受け付けられたファイルごとに、Received by the server の下に
bytes と sha256 を含む受信確認が追加されます。PDF のファイル名が付いた空ファイルも、この転送デモでは有効な入力であり、bytes: 0 を受け取りますが、有効な PDF 文書という意味ではありません。
この例では、一度に一組の選択ファイルを処理します。アップロード開始後は新たな選択をブロックします。同じ組の失敗したファイルを再試行するか、完了後に再読み込みして新しい組を選択してください。キャンセルすると選択がクリアされ、再度選択できます。すでに表示された受信確認は、再読み込みするまで残ります。
進捗バーの 100% は転送の進捗であり、サーバーが受け付けたことを示すものではありません。受信確認を追加するのは upload-success のみです。独自の実装では、Uppy の
complete イベントを、すべてのファイルが成功した証拠として扱わないでください。ファイルが失敗した場合も発火し、successful と failed の配列を個別に提供します。
サーバー側での検証の維持
クライアント側の制限は、データ送信前に誤りを発見しやすくしますが、別のクライアントなら回避できます。この受信サーバーはファイルサイズとファイル数を独自に制限しますが、MIME チェックでは依然として呼び出し元のメタデータを信頼しています。アップロードされたバイト列をレンダリング、実行、または配信することはありません。
公開サービスに応用する前に、認証と認可、受け付ける形式のコンテンツ検証、アプリケーションに適したストレージを追加してください。リクエスト数と同時実行数の制限も適用してください。ファイル単位の上限を小さくしても、多数の同時接続クライアントによる総メモリ使用量は制限できません。このデモはローカルループバックアドレスにのみバインドし、認証も永続ストレージも備えていません。
よくある問題のトラブルシューティング
CORS の設定
index.html をローカルファイルとして開くのではなく、表示された HTTP アドレスからページを配信してください。ページと
/upload は同一オリジンなので、この例に CORS ミドルウェアは不要です。API を別のオリジンに移す場合は、そのサーバーで実際のフロントエンドのオリジンと必要なヘッダーを許可してください。CORS はブラウザーによるレスポンスへのアクセスを制御します。アップロードリクエストを認証するものではありません。
ネットワークエラー
この例では、各試行を観察できるように shouldRetry: () => false で自動再試行を無効にしています。ページの読み込み後にサーバーを停止し、アップロードを試して
Dashboard の失敗状態を確認してください。同じポートで再起動するか、新しいアドレスで再読み込みしてファイルを選択し直してください。
固定した XHRUpload のバージョンでは、アップロードの進捗が 30 秒間ないと停滞の警告が出ますが、リクエストは終了しません。警告後でも、遅れてレスポンスが届けば完了することがあります。待機をやめたいリクエストは Cancel で中止してください。
同じエンドポイントへのリクエストが失敗した場合は、原因を解消してから Retry を選択してください。XHRUpload はそのファイルを最初から再送信します。レスポンスが失われると、サーバーがバイト列を受信済みでも、ブラウザーでは結果を判断できないことがあります。永続的なアップロードサービスには、独自の重複処理ポリシーが必要です。
許容範囲内の大きめのファイルとブラウザーのネットワーク速度制限を使い、処理が未完了の間にステータスバーの Cancel コントロールを試してください。キャンセルはブラウザーの未完了リクエストを中止し、選択をクリアしますが、サーバーが受信済みのバイト列は取り消せません。一時停止と再開の機能ではありません。
ファイル形式の検証
クライアント側の上限を超えるファイル、未対応の拡張子や形式、または六つ目のファイルは、そのファイルのアップロードを開始せずに Dashboard の選択エラーとなります。.pdf ルールはファイル名の拡張子を許可するもので、PDF の内容は検査しません。HTTP 415 は受信側が申告された MIME タイプを拒否したこと、HTTP 413 はサイズ制限を超えたことを示します。ブラウザーのネットワークパネルで
POST を調べてください。CORS 設定を変更しても、これらのレスポンスは解消しません。
再開が必要なアップロードでの tus の使用
XHRUpload は、通常のマルチパートエンドポイントや小さなファイルに適しています。同時実行数の上限を変更しても、チャンク分割や再開機能は追加されません。中断後の継続が必要なアップロードには、Uppy の Tus プラグインと tus 対応サーバーを使用してください。これは別のプロトコルなので、このマルチパート受信サーバーを置き換える必要があります。
