高效实现HTML表单文件上传至Node.js应用教程

DDD

发布时间：2025-11-17 12:31:00

1041人浏览过

来源于php中文网

原创

高效实现HTML表单文件上传至Node.js应用教程

本教程详细指导如何构建一个完整的web文件上传系统，涵盖html表单配置、node.js服务器端（express和multer）处理以及客户端javascript（fetch api）提交逻辑。文章将重点解决常见的配置错误，如表单提交方式、multer字段名不匹配等，确保用户能成功从前端上传文件至服务器指定目录。

在现代Web应用开发中，文件上传是一个常见且重要的功能。无论是用户头像、文档还是其他媒体文件，前端与后端之间的顺畅交互是实现这一功能的关键。本教程将引导您使用HTML构建前端表单，结合Node.js、Express框架和Multer中间件处理服务器端逻辑，并通过JavaScript的Fetch API实现文件的异步提交。我们将针对一个常见的上传问题进行剖析和修正，帮助您理解并正确实现文件上传功能。

核心概念概览

在深入实现之前，我们先了解涉及到的主要技术和它们在文件上传中的作用：

HTML <form> 元素: 负责定义文件上传的用户界面。关键属性包括 method="POST"、enctype="multipart/form-data" 和 input type="file"。
Node.js & Express: Node.js 是服务器端JavaScript运行环境，Express 是一个流行的Web应用框架，用于构建RESTful API和处理HTTP请求。
Multer: 专为Express设计的Node.js中间件，用于处理 multipart/form-data 类型的数据，主要用于文件上传。它简化了文件存储、命名等操作。
JavaScript (Fetch API): 用于在客户端发起HTTP请求，实现异步文件上传，避免页面刷新，提升用户体验。FormData 对象在此过程中用于封装文件数据。

1. HTML表单结构：准备上传接口

首先，我们需要一个HTML表单来允许用户选择文件。以下是用于文件上传的HTML表单的关键部分：

<html lang="ita">
  <head>
    <!-- 样式和脚本导入 -->
    <link rel="stylesheet" href="style.css" />
    <script
      type="text/javascript"
      src="https://code.jquery.com/jquery-latest.js"
    ></script>
    <script src="index-script.js"></script>
    <title>文件上传示例</title>
  </head>
  <body>
    <form
      method="POST"
      name="form"
      class="form vert-align"
      enctype="multipart/form-data"
    >
      <h1 class="first-page">文件上传到服务器</h1>

      <div class="container1">
        <label for="file" class="label-style-1 upload-label">上传文件</label>
        <input type="file" id="file" name="file" multiple hidden />
        <span>未选择文件</span>
      </div>

      <div class="container3">
        <label for="submit" class="label-style-1 submit-label" hidden>OK</label>
        <input type="submit" id="submit" name="submit" hidden />
        <label for="cancel" class="label-style-1 cancel-label" hidden
          >取消</label
        >
        <input type="reset" id="cancel" name="cancel" hidden />
      </div>
    </form>
  </body>
</html>

关键点说明：

立即学习“前端免费学习笔记（深入）”；

method="POST": 指定表单数据将通过POST方法发送。
enctype="multipart/form-data": 这是文件上传的核心！ 告诉浏览器不要使用默认的 application/x-www-form-urlencoded 编码，而是使用 multipart/form-data，以便能够传输二进制文件数据。
<input type="file" id="file" name="file" multiple hidden />: 这是文件选择输入框。
- type="file": 允许用户选择一个或多个文件。
- name="file": 定义了服务器端接收文件时使用的字段名。
- multiple: 允许用户选择多个文件。
- hidden: 隐藏原生文件输入框，通过 <label> 元素实现自定义样式。
注意： 在这里，我们移除了 <form> 标签上的 action="/upload" 属性。因为我们将通过JavaScript的Fetch API来手动处理表单提交，而不是依赖浏览器默认的表单提交行为。

2. Node.js服务器端配置：使用Express和Multer处理文件

服务器端需要配置Express来监听请求，并使用Multer中间件来解析和存储上传的文件。

首先，确保您的项目已安装必要的依赖：

npm install express multer path

接下来，创建或修改您的 app.js 文件（或任何您的Node.js应用入口文件）：

一点PPT

一句话生成专业PPT，AI自动排版配图

下载

/* 必要的模块 */
const express = require("express");
const path = require("path");
const multer = require("multer");

/* 配置Multer的存储引擎 */
const storage = multer.diskStorage({
  destination: (req, file, cb) => {
    // 指定文件上传的目录。请确保 'uploads' 目录存在于项目根目录。
    cb(null, "uploads");
  },
  filename: (req, file, cb) => {
    // 定义上传文件的文件名，这里使用时间戳+原始文件名，避免文件名冲突
    cb(null, Date.now() + "-" + path.basename(file.originalname));
  },
});

const upload = multer({ storage: storage });

/* 创建Express应用实例 */
const app = express();

// 提供静态文件，例如HTML、CSS、JS等
app.use(express.static(path.join(__dirname, "public")));
// 如果您的index.html在public目录下，可以通过以下方式提供
// app.use(express.static(path.join(__dirname, 'public')));
// 否则，如果index.html在项目根目录，或者需要特定路由访问
app.get("/", (req, res) => {
  // 假设您的index.html在项目的根目录，或者在public/assets目录下
  // 根据实际文件路径调整
  res.sendFile(path.join(__dirname, "index.html")); // 或 path.join(__dirname, 'public', 'index.html')
});

/* 定义文件上传的POST路由 */
// Multer中间件在这里处理文件上传。
// upload.array("files") 表示期望接收一个名为 "files" 的文件数组。
// 注意：这里的字段名 "files" 必须与前端 FormData.append() 中使用的名称一致。
app.post("/upload", upload.array("files"), (req, res) => {
  console.log("文件上传成功！");
  console.log("上传的文件信息:", req.files); // Multer会将文件信息添加到 req.files
  res.send("文件已成功上传！");
});

/* 处理所有未匹配的请求（404错误） */
app.use((req, res) => {
  res.status(404);
  res.send("<h1>错误 404: 资源未找到</h1>");
});

/* 启动服务器并监听3000端口 */
app.listen(3000, () => {
  console.log("服务器运行在 http://localhost:3000");
});

关键点说明：

立即学习“前端免费学习笔记（深入）”；

multer.diskStorage: 配置了文件的存储方式。
- destination: 指定文件保存的目录。这里是 uploads。请确保该目录在您的项目根目录下存在，否则Multer会报错。
- filename: 定义保存文件的名称。这里使用了 Date.now() + "-" + path.basename(file.originalname)，以当前时间戳加上原始文件名来生成唯一的文件名。
upload.array("files"): 这是Multer中间件的关键。
- array() 方法表示期望接收多个文件。
- "files" 是指前端通过 FormData.append() 方法添加文件时使用的字段名。请注意，这个名称必须与前端JavaScript代码中的 formData.append("files", ...) 完全匹配。 原始问题中的错误就是这里使用了 upload.array("file") 而前端使用了 formData.append("files", ...) 导致不匹配。
app.get("/", ...): 这是一个可选但推荐的路由，用于在访问根路径时提供 index.html 文件。
req.files: 当文件通过 upload.array() 上传成功后，Multer会将所有上传文件的信息存储在 req.files 数组中。

3. 客户端JavaScript逻辑：使用Fetch API提交文件

客户端JavaScript负责监听文件选择事件，将选中的文件添加到 FormData 对象中，并在用户点击提交按钮时，通过Fetch API将 FormData 发送到Node.js服务器。

/* 格式化数字，添加千位分隔符 */
function numberWithDots(x) {
  return x.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ".");
}

let myFiles = []; // 用于存储用户选择的文件列表
let formData = new FormData(); // FormData对象用于封装文件数据

$(document).ready(function () {
  // 取消按钮点击事件：重新加载页面
  $("#cancel").on("click", function () {
    location.reload();
  });

  // 提交按钮点击事件：通过Fetch API发送文件
  $("#submit").on("click", function (e) {
    e.preventDefault(); // 阻止表单默认提交行为

    // 检查是否有文件要上传
    if (myFiles.length === 0) {
      alert("请选择文件进行上传！");
      return;
    }

    // 清空旧的formData，重新添加当前myFiles中的文件
    formData = new FormData();
    for (let i = 0; i < myFiles.length; i++) {
      let file = myFiles[i];
      // 这里的 "files" 必须与Node.js Multer配置中的 upload.array("files") 匹配
      formData.append("files", file, file.name);
    }

    // 使用Fetch API发送POST请求
    fetch("http://localhost:3000/upload", {
      method: "POST", // 请求方法为POST
      body: formData, // 请求体为FormData对象，浏览器会自动设置正确的Content-Type
      // 注意：当使用FormData作为body时，不要手动设置Content-Type，浏览器会自动处理
    })
      .then((res) => {
        if (!res.ok) {
          throw new Error(`HTTP error! status: ${res.status}`);
        }
        return res.text(); // 或者 res.json()，取决于服务器返回的数据类型
      })
      .then((data) => {
        console.log("上传响应:", data);
        alert("文件上传成功！");
        // 文件上传成功后，可以重定向到其他页面或更新UI
        // window.open("results.html", "_self"); // 如果需要，可以重新启用
      })
      .catch((err) => {
        console.error("文件上传发生错误:", err);
        alert("文件上传失败，请检查控制台。");
      });
  });

  // 文件选择输入框的change事件：处理用户选择的文件
  $("#file").on("change", (event) => {
    myFiles = Array.from(event.target.files); // 将FileLits转换为数组方便操作

    /* 创建一个容器来显示文件列表 */
    $(".container1").html(
      "<div class='container2'>" +
        "<span class='pop-head'>已选择文件:</span> <ul></ul></div>"
    );

    $(".first-page").css("margin-top", "10vh");

    /* 遍历并显示每个选中的文件 */
    for (let i = 0; i < myFiles.length; i++) {
      const file = myFiles[i];
      $("ul").append(
        "<li><div class='container4'><span download>" +
          file.name +
          " (" +
          numberWithDots(Math.floor(file.size / 1024 + 1)) +
          " KB)</span>    " +
          "<label for='remove" +
          i +
          "' class='label-style-1 remove' id='lab" +
          i +
          "'>移除</label>" +
          "<input type='button' id='remove" +
          i +
          "' name='remove" +
          i +
          "' hidden>" +
          "</div></li>"
      );
    }

    /* 移除上传文件按钮，显示OK和CANCEL按钮 */
    $(".upload-label").remove();
    $("#file").remove();
    $(".submit-label").show();
    $(".cancel-label").show();

    /* 移除文件功能（客户端模拟） */
    $(".remove").on("click", function () {
      let index = $(this).attr("id').replace("lab", "");
      // 从 myFiles 数组中移除对应的文件
      myFiles.splice(index, 1);
      // 移除对应的DOM元素
      $(this).closest("li").remove();

      // 如果所有文件都被移除，恢复初始界面
      if (myFiles.length === 0) {
        location.reload(); // 简单粗暴地刷新页面恢复初始状态
      }
    });
  });
});

关键点说明：

立即学习“前端免费学习笔记（深入）”；

e.preventDefault(): 在 $("#submit").on("click", ...) 事件处理函数中，e.preventDefault() 是至关重要的。它阻止了浏览器执行表单的默认提交行为（即向 action 属性指定的URL发起同步请求），从而允许我们使用JavaScript进行异步提交。
FormData 对象:
- let formData = new FormData();: 创建一个新的 FormData 实例。
- formData.append("files", file, file.name);: 将文件添加到 FormData 对象中。
  - "files": 这是服务器端Multer期望接收的字段名。必须与 upload.array("files") 中的 "files" 保持一致。
  - file: 实际的文件对象。
  - file.name: 文件的原始名称（可选，但推荐）。
fetch("http://localhost:3000/upload", { ... }):
- method: 'POST': 指定HTTP请求方法为POST。
- body: formData: 将 FormData 对象作为请求体发送。当 body 是 FormData 实例时，浏览器会自动设置 Content-Type 为 multipart/form-data 并包含正确的 boundary，因此您不需要手动设置 Content-Type 请求头。 如果手动设置，可能会导致问题。
.then().catch(): 处理Fetch API的响应和可能发生的错误。

4. 样式文件 (CSS)

为了提供更好的用户体验，这里也包含了原始问题中的CSS样式，您可以根据需要进行调整。CSS文件 (style.css) 的内容将保持不变，因为它主要负责页面布局和美观，不直接影响文件上传的逻辑。

/* ... (原始CSS代码，保持不变) ... */
@font-face {
  font-family: WorkSans;
  src: url("assets/fonts/WorkSans.ttf");
}
* {
  font-family: "WorkSans";
}

/*---------Chromium---------*/
/* width */
::-webkit-scrollbar {
  width: 10px;
}

/* Track */
::-webkit-scrollbar-track {
  background: #595959;
}

/* Handle */
::-webkit-scrollbar-thumb {
  background: #f1ca13;
}

/* Handle on hover */
::-webkit-scrollbar-thumb:hover {
  background: #c19f0b;
}

/*---------Mozilla---------*/
html {
  scrollbar-width: 10px;
  scrollbar-color: #f1ca13 #595959;
}

body {
  background-color: #383838;
  font-weight: 300;
  font-size: 20pt;
  margin: 0px;
  overflow-y: scroll;
}

.form {
  background-color: #383838;
  color: white;

  width: 70vw;
  margin: auto;

  text-align: center;
}

.vert-align {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
}

.sticky {
  position: fixed;
  top: 0;
  width: 100%;
  text-align: center;
}
.content {
  padding-top: 50px;
}

h1 {
  font-size: 60pt;
  color: #f1ca13;
  background-color: #383838;
  margin-bottom: 50px;
}
.first-page {
  margin-top: 40vh;
}

span {
  color: white;
}
ul {
  list-style-type: none;
}
li {
  padding: 15px;
  margin: 15px;
  border: 1px solid #696969;
  cursor: default;
}

.label-style-1 {
  padding: 3px 20px;
  border-radius: 30px;
  border: 3px solid black;
  background-color: black;
  transition: all 200ms linear;
  font-size: 20px;
}
.label-style-1:hover {
  border: 3px solid white;
  background-color: white;
  color: black;
  cursor: pointer;
}

.upload-label {
  width: 150px;
}

.submit-label {
  width: 30px;
}

.pop-head {
  font-size: 25pt;
  color: #f1ca13;
  font-weight: bold;
}

.container2 {
  width: 60vw;
  padding: 40px;

  text-align: left;

  border: 3px solid white;
  border-radius: 10px;
}
.container2 ul {
  display: flex;
  flex-direction: column;
}

.container2 li:hover {
  background-color: #595959;
  cursor: default;
}

.container3 {
  padding: 30px;
}

.container4 {
  display: flex;
  align-items: center;
}

.container5 {
  padding: 15px;
  margin: 15px;
  border: 1px solid #696969;
  cursor: default;
}

.container6 {
  text-align: center;
  width: 44rem;
}

.container7 {
  cursor: pointer;
  width: fit-content;
}

.remove {
  margin-left: auto; /* aligns to the right */
}

/* -------------------------results------------------------- */
.results {
  overflow-y: scroll;
  color: white;
  display: flex;
  align-items: center;
  min-height: 100vh;
  flex-direction: column;
}

.file {
  width: fit-content;
  display: inline-block;
}

.details {
  display: inline-block;
  position: relative;
  margin-left: 10px;
  font-size: 10pt;
  color: #f1ca13;
  transition: all 200ms linear;
}

.details:hover {
  color: #b5960f;
}

.details::after {
  content: "";
  position: absolute;

修复 clientHeight 在窗口缩放时无法动态减小的问题

修复 clientHeight 在窗口缩放时无法正确响应高度变化的问题

HTML 文件分离时 collapsible 无法折叠的解决方案

如何正确协调 mouseDown/mouseUp 与 hover 交互效果

如何正确协调鼠标按下、释放与悬停事件的样式优先级