使用 fetch/axios 实现文件上传的方法｜FormData、进度条、错误处理

在现代网络应用中实现文件上传时，使用 <code>fetch</code> API 或 <code>axios</code> 进行异步文件发送已成为标准。虽然简单的发送可以用几行代码实现，但考虑进度条、错误处理、大文件分块、CORS 支持等因素会涉及许多要点。本文将系统地解释所有这些内容。

FormData 的使用方法（append / set）

<code>FormData</code> 是一个 API，用于在 JavaScript 中构建与 HTML 表单的 <code>enctype="multipart/form-data"</code> 等价的数据。它可以处理整个表单数据，包括不仅是文件，还有文本字段。

// input[type="file"] からファイルを取得
const fileInput = document.querySelector('#file-input');
const file = fileInput.files[0];

// FormData を作成
const formData = new FormData();

// append: 同名のキーで複数の値を追加できる
formData.append('file', file);
formData.append('file', anotherFile); // 複数ファイルを同じキーで送れる
formData.append('description', 'アップロードテスト');
formData.append('userId', '12345');

// set: 既存のキーがあれば上書き（追加ではなく置換）
formData.set('file', newFile); // 既存の 'file' エントリをすべて削除して置換

// 中身の確認
for (const [key, value] of formData.entries()) {
    console.log(key, value);
}

// 複数ファイルを input[type="file" multiple] から追加する場合
const multipleFiles = fileInput.files;
Array.from(multipleFiles).forEach(f => {
    formData.append('files[]', f);
});

使用fetch进行文件上传

使用 <code>fetch</code> 发送 FormData 时，重要的是 <strong>不要手动设置 Content-Type 标头</strong>。

async function uploadWithFetch(file) {
    const formData = new FormData();
    formData.append('file', file);
    formData.append('name', file.name);

    // NG: Content-Type を手動で設定してはいけない
    // fetch('/upload', {
    //     method: 'POST',
    //     headers: { 'Content-Type': 'multipart/form-data' }, // ← これは誤り！
    //     body: formData,
    // });

    // OK: Content-Type は fetch が自動で設定する（boundary パラメータも含む）
    const response = await fetch('/api/upload', {
        method: 'POST',
        body: formData,
        // headers は指定しない（または Content-Type 以外のヘッダーのみ指定）
    });

    if (!response.ok) {
        const error = await response.json().catch(() => ({ message: 'Unknown error' }));
        throw new Error(`Upload failed: ${response.status} - ${error.message}`);
    }

    return response.json();
}

// 使用例
const fileInput = document.querySelector('#file-input');
fileInput.addEventListener('change', async (e) => {
    const file = e.target.files[0];
    if (!file) return;

    try {
        const result = await uploadWithFetch(file);
        console.log('アップロード成功:', result);
    } catch (err) {
        console.error('アップロード失敗:', err.message);
    }
});

为什么不应该手动设置 Content-Type：<code>multipart/form-data</code> 请求需要 <code>boundary</code> 参数（例如：<code>boundary=----WebKitFormBoundaryXXX</code>），浏览器会根据 FormData 自动生成。如果手动设置 <code>Content-Type: multipart/form-data</code>，boundary 将会丢失，服务器将无法解析。

使用fetch显示进度(ReadableStream)

使用fetch API可以通过<code>ReadableStream</code>获取响应接收进度，但<strong>无法仅使用fetch获取上传进度</strong>。如果需要上传进度，请使用axios或XMLHttpRequest。

// fetch でダウンロード進捗を取得する例（アップロードとは逆方向）
async function downloadWithProgress(url, onProgress) {
    const response = await fetch(url);
    const contentLength = response.headers.get('Content-Length');
    const total = parseInt(contentLength, 10);
    let loaded = 0;

    const reader = response.body.getReader();
    const chunks = [];

    while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        chunks.push(value);
        loaded += value.length;
        onProgress(loaded, total);
    }

    return new Blob(chunks);
}

使用axios上传 + 使用onUploadProgress实现进度条

axios可以通过<code>onUploadProgress</code>回调获取上传进度。由于它包装了XMLHttpRequest，可以利用浏览器的上传进度事件。

import axios from 'axios';

async function uploadWithAxios(file, onProgress) {
    const formData = new FormData();
    formData.append('file', file);

    const response = await axios.post('/api/upload', formData, {
        headers: {
            // axios は FormData を自動検出して Content-Type を設定するが、
            // 明示的に undefined を指定して axios に任せることもできる
        },
        onUploadProgress: (progressEvent) => {
            if (progressEvent.total) {
                const percent = Math.round(
                    (progressEvent.loaded * 100) / progressEvent.total
                );
                onProgress(percent);
            }
        },
        // タイムアウト設定（ミリ秒）
        timeout: 300000, // 5分
    });

    return response.data;
}

// プログレスバーと組み合わせた使用例
const progressBar = document.querySelector('#progress-bar');
const progressText = document.querySelector('#progress-text');

async function handleUpload(file) {
    try {
        const result = await uploadWithAxios(file, (percent) => {
            progressBar.style.width = `${percent}%`;
            progressBar.setAttribute('aria-valuenow', percent);
            progressText.textContent = `${percent}%`;
        });
        console.log('完了:', result);
    } catch (err) {
        if (axios.isAxiosError(err)) {
            console.error('ステータス:', err.response?.status);
            console.error('メッセージ:', err.response?.data?.message);
        } else {
            console.error('予期しないエラー:', err);
        }
    }
}

大文件的分块上传

对于单个请求无法发送的文件大小（数百MB至GB），可将其分割成块（小单位）分别发送。服务器端接收每个块，最后进行合并。

const CHUNK_SIZE = 5 * 1024 * 1024; // 5MiB ずつ分割

async function uploadInChunks(file, onProgress) {
    const totalChunks = Math.ceil(file.size / CHUNK_SIZE);
    const uploadId = crypto.randomUUID(); // アップロードセッションID

    for (let i = 0; i < totalChunks; i++) {
        const start = i * CHUNK_SIZE;
        const end = Math.min(start + CHUNK_SIZE, file.size);
        const chunk = file.slice(start, end);

        const formData = new FormData();
        formData.append('chunk', chunk);
        formData.append('uploadId', uploadId);
        formData.append('chunkIndex', String(i));
        formData.append('totalChunks', String(totalChunks));
        formData.append('filename', file.name);

        await fetch('/api/upload/chunk', {
            method: 'POST',
            body: formData,
        });

        // 各チャンク送信後に進捗を更新
        const percent = Math.round(((i + 1) / totalChunks) * 100);
        onProgress(percent);
    }

    // 全チャンク送信後にサーバーへ結合を指示
    const response = await fetch('/api/upload/complete', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ uploadId, filename: file.name }),
    });

    return response.json();
}

错误处理（413 / 网络错误 / 超时）

按模式处理文件上传中可能发生的错误。

async function robustUpload(file) {
    const formData = new FormData();
    formData.append('file', file);

    try {
        const response = await fetch('/api/upload', {
            method: 'POST',
            body: formData,
            signal: AbortSignal.timeout(60000), // 60秒でタイムアウト
        });

        // ステータスコード別のエラー処理
        if (response.status === 413) {
            throw new Error('ファイルサイズが大きすぎます。サーバーの上限を超えています。');
        }

        if (response.status === 415) {
            throw new Error('サポートされていないファイル形式です。');
        }

        if (response.status === 422) {
            const data = await response.json();
            throw new Error(`バリデーションエラー: ${data.message}`);
        }

        if (!response.ok) {
            throw new Error(`サーバーエラー: ${response.status} ${response.statusText}`);
        }

        return await response.json();

    } catch (err) {
        if (err.name === 'AbortError' || err.name === 'TimeoutError') {
            throw new Error('アップロードがタイムアウトしました。ネットワーク接続を確認してください。');
        }

        if (err instanceof TypeError && err.message.includes('Failed to fetch')) {
            throw new Error('ネットワークエラーが発生しました。接続を確認してください。');
        }

        throw err; // それ以外は再スロー
    }
}

CORS 配置要点

当上传到不同源(域名或端口)的API时，需要配置CORS(跨源资源共享)。包含multipart/form-data的POST请求不是"简单请求"，会触发预检请求(OPTIONS方法)。

// フロントエンド側：特別な設定は不要（ブラウザが自動でプリフライトを送信）
const response = await fetch('https://api.example.com/upload', {
    method: 'POST',
    body: formData,
    // credentials: 'include', // クッキーを含む場合（サーバー側で credentials: true が必要）
});

# Nginx でのCORS設定例
location /api/upload {
    # プリフライトリクエスト（OPTIONS）への応答
    if ($request_method = 'OPTIONS') {
        add_header 'Access-Control-Allow-Origin' 'https://frontend.example.com';
        add_header 'Access-Control-Allow-Methods' 'POST, OPTIONS';
        add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type';
        add_header 'Access-Control-Max-Age' '86400';
        add_header 'Content-Length' '0';
        return 204;
    }

    add_header 'Access-Control-Allow-Origin' 'https://frontend.example.com';
    proxy_pass http://app_backend;
}

关于文件上传，CORS 中需要特别注意的点：

• 在 <code>Access-Control-Allow-Headers</code> 中包含 <code>Content-Type</code> 可能会导致误解认为浏览器可以自由设置 Content-Type
• 使用 FormData 时，由于未自定义设置 Content-Type 标头，可能不会发生预检请求
• 通过 <code>Authorization</code> 头发送认证令牌时，必然会发生预检请求。