axios/docs/zh/pages/advanced/file-posting.md

文件上传

axios 让文件上传变得简单。需要 multipart/form-data 上传时，使用 postForm 或 FormData 即可。

单文件上传（浏览器）

直接将 File 对象作为字段值传入——axios 会自动检测并使用正确的内容类型：

await axios.postForm("https://httpbin.org/post", {
  description: "My profile photo",
  file: document.querySelector("#fileInput").files[0],
});

多文件上传（浏览器）

传入 FileList 可一次性上传所有选中的文件，所有文件将使用相同的字段名（files[]）发送：

await axios.postForm(
  "https://httpbin.org/post",
  document.querySelector("#fileInput").files
);

也可以通过在键名末尾追加 [] 来显式指定一个自定义字段名，传入 FileList（或 File 对象数组）：

await axios.postForm("https://httpbin.org/post", {
  "files[]": document.querySelector("#fileInput").files,
});

如需为每个文件使用不同的字段名，请手动构建 FormData 对象：

const formData = new FormData();
formData.append("avatar", avatarFile);
formData.append("cover", coverFile);

await axios.post("https://httpbin.org/post", formData);

跟踪上传进度（浏览器）

使用 onUploadProgress 回调向用户显示进度条或百分比：

await axios.postForm("https://httpbin.org/post", {
  file: document.querySelector("#fileInput").files[0],
}, {
  onUploadProgress: (progressEvent) => {
    const percent = Math.round(
      (progressEvent.loaded * 100) / progressEvent.total
    );
    console.log(`Upload progress: ${percent}%`);
  },
});

进度事件对象上可用的完整字段列表，请参阅进度捕获。

Node.js 中的文件上传

在 Node.js 中，使用 fs.createReadStream 上传文件系统中的文件，无需将整个文件加载到内存：

import fs from "fs";
import FormData from "form-data";
import axios from "axios";

const form = new FormData();
form.append("file", fs.createReadStream("/path/to/file.jpg"));
form.append("description", "My uploaded file");

await axios.post("https://httpbin.org/post", form);

::: tip 在 Node.js 环境中创建 FormData 对象需要 form-data npm 包。在现代 Node.js（v18+）中，全局 FormData 已原生可用。 :::

上传 Buffer（Node.js）

也可以直接上传内存中的 Buffer：

const buffer = Buffer.from("Hello, world!");

const form = new FormData();
form.append("file", buffer, {
  filename: "hello.txt",
  contentType: "text/plain",
  knownLength: buffer.length,
});

await axios.post("https://httpbin.org/post", form);

::: warning Node.js 环境目前不支持捕获 FormData 上传进度。 :::

::: danger 在 Node.js 中上传可读流时，请设置 maxRedirects: 0，以防止 follow-redirects 包将整个流缓冲到内存中。 :::