Koa.js 实现文件上传接口：从中间件配置到前端测试

Koa.js文件上传接口实现概述

文件上传是各类系统中不可或缺的基础功能，常见场景包括图片存储、Excel表格上传等。本文将指导读者如何在Node.js的Koa框架中构建一个支持文件上传的接口，内容涵盖从初始环境配置到最终使用Postman及HTML页面进行功能验证的全过程。

环境准备与项目初始化

01—环境准备

首先，需要初始化一个Koa项目。只需安装核心依赖库 Koa 以及路由中间件 koa-router 即可开始开发。

npm install koa koa-router

接下来需配置图片存储目录，将上传的文件定向保存至指定路径。在应用根路径下新建 public 文件夹，项目目录结构如下所示：

koa-upload/

--app

----public

------uploads

----index.js

--package.json

编写 index.js 入口文件，初始化应用实例并配置基础路由。

const koa = require('koa')
const app = new koa()
router.post('/upload', ctx => {
  ctx.body = 'koa upload demo'
})
app.use(router.routes());
app.listen(3000, () => {
  console.log('启动成功')
  console.log('http://localhost:3000')
});

启动服务，确认应用能正常运行且无报错，确保基础环境无误。

使用koa-body处理文件上传

02—使用 koa-body 中间件获取上传的文件

koa-body 中间件能够解析文件、JSON 及 form 格式的请求体。首先需安装该依赖库。

  npm install koa-body

在 index.js 中配置 koaBody 参数，指定支持 multipart 格式并设置上传目录及保留扩展名等选项。

const koa = require('koa')
const koaBody = require('koa-body')
const path = require('path')
const app = new koa()
app.use(koaBody({
  // 支持文件格式
  multipart: true,
  formidable: {
    // 上传目录
    uploadDir: path.join(__dirname, 'public/uploads'),
    // 保留文件扩展名
    keepExtensions: true,
  }
}));

... ...

完善 /upload 路由逻辑，从请求中获取文件对象，并将其路径直接返回给客户端。

router.post('/upload', ctx => {
  const file = ctx.request.files.file
  ctx.body = { path: file.path }
})

此时，文件上传功能已初步实现，文件将被保存至 public/uploads 目录。接下来使用 Postman 工具进行接口测试。

打开 Postman，输入地址 http://localhost:3001/upload，选择 POST 请求方法。在 Body 选项卡中选择 form-data 格式，KEY 列选择 file 类型，以便上传文件。

选择本地图片进行上传，成功后可在 uploads 文件夹中查看到该图片，控制台也会输出文件保存路径。

配置koa-static生成图片访问链接

03—使用 koa-static 中间件生成图片链接

仅返回本地文件路径在实际业务中价值有限，我们需要返回一个可通过 HTTP 访问的图片链接，以便用户点击即可查看。

借助 koa-static 中间件可以构建静态文件服务。该中间件指定一个目录，使该目录下的所有文件均可通过 HTTP 服务访问。

安装依赖： npm install koa-static 并将其注册到 Koa 应用实例中。需将其注册在 koaBody 中间件之前，并将 public 目录设置为静态文件根目录。

const koaStatic = require('koa-static')
... ...
app.use(koaStatic(path.join(__dirname, 'public')))

启动程序后，public 目录下的文件即可通过 HTTP 服务访问。尝试访问之前上传的图片地址：http://localhost:3001/uploads/upload_65c1d26e5a47870cf4011aad1243fce0.png，浏览器中可直接显示图片。

随后改造 upload 路由的实现逻辑，使其在响应中生成并返回图片的完整 URL 链接。

router.post('/upload', ctx => {
  const file = ctx.request.files.file
  const basename = path.basename(file.path)
  ctx.body = { "url": `${ctx.origin}/uploads/${basename}` }
})

利用 path.basename 获取文件的名称及扩展名，通过 ctx.origin 获取服务器域名（如 localhost:3001），注意避免硬编码域名。

再次使用 Postman 测试接口，即可看到返回的包含图片 URL 的 JSON 数据，点击链接可直接打开图片。

前端HTML表单上传测试

04—编写前端页面上传文件

前文使用 Postman 模拟了文件上传测试，虽然后端接口测试高效，但部分前端开发者更习惯通过前端页面进行测试。因此，我们将编写一个表单页面来进行验证。

在 public 目录下新建 upload.html 文件，作为前端测试页面。

<form action="/upload" method="POST" enctype="multipart/form-data">
  <input type="file" name="file">
  <button type="submit">上传</button>
</form>

这是一个传统的表单提交示例，实际工作中此类代码虽不常见，但原理清晰。action 属性指定提交接口地址，enctype="multipart/form-data" 用于指定上传格式为 multipart/form-data。input 标签的 name 属性必须设为 file，以匹配后端接收的字段名。

使用 HTTP 服务打开该页面：http://localhost:3001/upload.html。由于 public 目录已配置为静态服务目录，其中的文件均可通过 HTTP 访问。

在页面中选择文件并点击上传，成功后页面会返回文件地址信息。

总结

以上介绍了在 Koa.js 中实现文件上传接口的完整流程，希望能为读者提供帮助。如有任何疑问，欢迎留言交流，小编会及时回复。感谢大家对本站的支持！ 如果觉得本文对您有帮助，欢迎转载，请注明出处，谢谢！