Koa2中/contact接口功能正常却返回404错误的原因分析

这问题我碰到过好几次，核心原因其实很简单：你的路由处理函数没有给客户端返回任何HTTP响应。

Koa2的工作机制是基于中间件的，每个请求都需要明确结束响应周期——要么设置ctx.body、ctx.status这类响应内容，要么调用ctx.redirect之类的方法告诉Koa“这个请求我处理完了”。如果你的代码里只调用了Mailgun的发送邮件逻辑，却没做任何响应处理，Koa就会认为这个请求还没被处理完，会继续往下找匹配的路由，最后找不到就返回404。

结合你说邮件能正常发送，说明路由是匹配到了，问题就出在响应环节，大概率是这两种情况：

1. 异步邮件发送的回调里没处理响应 #

如果你的代码是用回调方式调用Mailgun的send方法，却只在回调里打印日志，没设置响应：

router.post('/contact', (ctx) => {
  const { name, email, message } = ctx.request.body;
  mailgun.messages().send({/* 邮件参数 */}, (err, body) => {
    if (err) console.error(err);
    else console.log(body);
    // 这里没设置ctx.body或ctx.status！
  });
  // 函数直接结束，Koa没收到响应信号
});

这种情况下，路由函数会先执行完，Mailgun的异步回调后续才会触发，但Koa已经在等待响应了，等不到就返回404。

2. 用了async/await但没正确等待异步操作 #

如果是用async函数，但没await Mailgun的异步操作，或者await了却没设置响应：

router.post('/contact', async (ctx) => {
  const params = ctx.request.body;
  // 没await的话，函数直接返回，Koa结束请求
  mailgun.messages().send(params);
});

怎么解决？ #

不管邮件发送成功还是失败，都要明确给客户端返回响应，同时正确处理异步逻辑：

方法一：用Promise包装回调（如果Mailgun不支持Promise的话）

// 先把Mailgun的send方法包装成Promise
const sendContactEmail = (data) => {
  return new Promise((resolve, reject) => {
    mailgun.messages().send(data, (err, body) => {
      err ? reject(err) : resolve(body);
    });
  });
};

// 路由处理函数
router.post('/contact', async (ctx) => {
  try {
    const { name, email, message } = ctx.request.body;
    // 等待邮件发送完成
    await sendContactEmail({
      from: `${name} <${email}>`,
      to: 'your-target-email@example.com',
      subject: '新的联系表单提交',
      text: message
    });
    // 返回成功响应
    ctx.status = 200;
    ctx.body = { success: true, message: '邮件发送成功' };
  } catch (error) {
    console.error('邮件发送失败:', error);
    // 返回错误响应
    ctx.status = 500;
    ctx.body = { success: false, message: '邮件发送失败，请稍后重试' };
  }
});

方法二：直接用Mailgun的Promise版本

现在很多第三方库都支持Promise了，如果Mailgun的send方法返回Promise，直接await就行：

router.post('/contact', async (ctx) => {
  try {
    const { name, email, message } = ctx.request.body;
    await mailgun.messages().send({/* 邮件参数 */});
    ctx.status = 200;
    ctx.body = { success: true };
  } catch (err) {
    ctx.status = 500;
    ctx.body = { success: false, error: err.message };
  }
});

最后别忘了确认路由已经正确注册到Koa实例上：

const Koa = require('koa');
const router = require('./your-router-file');

const app = new Koa();
// 注册路由和允许的HTTP方法
app.use(router.routes()).use(router.allowedMethods());

app.listen(3000);

这样修改后，客户端就能收到正确的响应，不会再返回404了。

内容的提问来源于stack exchange，提问作者Mark Brown