Midway.js¶

适用于基于 Koa 的 Midway.js 3（Node.js 18+）应用的分步指南。Mailexam 通过 @Provide() 服务中的 Nodemailer 以 SMTP 方式接入。

所需条件¶

Mailexam 账户及带 SMTP 凭据的项目。
Midway 3 项目（CLI：npm init midway@latest -- --type=koa-v3）。

从欢迎邮件（或控制台）复制以下信息：

YOUR_LOGIN — SMTP 登录名（例如 xxxxx）；
YOUR_PASSWORD — SMTP 密码（与登录名配对）；
主机 — YOUR_LOGIN.mailexam.cn（与登录名一致）。

1. 依赖¶

npm install nodemailer dotenv
npm install -D @types/nodemailer

Midway Koa 启动模板已包含 @midwayjs/koa、@midwayjs/core 和 @midwayjs/bootstrap。

2. 环境变量¶

在项目根目录创建 .env（勿提交密码）：

MAILEXAM_LOGIN=YOUR_LOGIN
MAILEXAM_PASSWORD=YOUR_PASSWORD
MAILEXAM_PORT=587
MAIL_FROM=noreply@example.test

在 bootstrap 之前加载 .env（例如在 bootstrap.js 中）：

require('dotenv').config();

const { Bootstrap } = require('@midwayjs/bootstrap');
Bootstrap.run();

SMTP 主机：YOUR_LOGIN.mailexam.cn。

发件人地址

MAIL_FROM 可以是任意测试地址 — 邮件会进入 Mailexam，而非真实收件人。

备选端口¶

587 + STARTTLS（推荐）2525465（SMTPS）

MAILEXAM_PORT=587

transport 中：secure: false（587 端口 STARTTLS）。

MAILEXAM_PORT=2525

MAILEXAM_PORT=465

transport 中设置 secure: true。

3. 邮件服务¶

src/service/mail.service.ts：

import { Provide } from '@midwayjs/core';
import * as nodemailer from 'nodemailer';
import type { Transporter } from 'nodemailer';

@Provide()
export class MailService {
  private createTransport(): Transporter {
    const login = process.env.MAILEXAM_LOGIN!;
    const port = Number(process.env.MAILEXAM_PORT || 587);

    return nodemailer.createTransport({
      host: `${login}.mailexam.cn`,
      port,
      secure: port === 465,
      auth: {
        user: login,
        pass: process.env.MAILEXAM_PASSWORD,
      },
    });
  }

  async sendTest(to: string, subject: string, text: string): Promise<void> {
    const from = process.env.MAIL_FROM || 'noreply@example.test';

    await this.createTransport().sendMail({ from, to, subject, text });
  }
}

4. 测试路由¶

src/controller/mail.controller.ts：

import { Body, Controller, Inject, Post } from '@midwayjs/core';
import { MailService } from '../service/mail.service';

interface SendMailBody {
  to?: string;
  subject?: string;
  text?: string;
  body?: string;
}

@Controller('/mail')
export class MailController {
  @Inject()
  mailService: MailService;

  @Post('/test')
  async test(@Body() body: SendMailBody) {
    await this.mailService.sendTest(
      body.to ?? 'user@example.test',
      body.subject ?? 'Midway + Mailexam',
      body.text ?? body.body ?? 'Mailexam test from Midway.js'
    );

    return { status: 'ok' };
  }
}

Midway Koa 默认 HTTP 端口为 7001（src/config/config.default.ts 中的 koa.port）。

启动并验证：

npm run build
npm start

curl -X POST http://127.0.0.1:7001/mail/test \
  -H 'Content-Type: application/json' \
  -d '{"to":"user@example.test","subject":"Test","text":"Hello"}'

邮件将出现在 Mailexam 控制台 → 您的项目 → 收件箱。

5. 本地开发与 CI¶

环境	建议
`local`	`.env` + 在 `bootstrap.js` 中使用 `dotenv`
CI	在 GitLab CI/CD Variables 中设置 `MAILEXAM_LOGIN`、`MAILEXAM_PASSWORD`

GitLab CI 示例：

variables:
  MAILEXAM_LOGIN: $MAILEXAM_LOGIN
  MAILEXAM_PASSWORD: $MAILEXAM_PASSWORD
  MAILEXAM_PORT: "587"
  MAIL_FROM: "noreply@example.test"

集成测试发送邮件后，通过 Mailexam API 验证投递。

6. 常见问题¶

连接超时 / 认证失败

host 必须为 {login}.mailexam.cn，auth.user 为邮件中的同一登录名。
登录名与密码为同一项目的配对凭据。

587 端口与 TLS

587 使用 secure: false（STARTTLS）。465 使用 secure: true。

变量为 undefined

在 Bootstrap.run() 之前于 bootstrap.js 中加载 .env，或在 CI 中导出变量。

控制台中看不到邮件

查看同一 Mailexam 项目的收件箱。
检查 sendMail 时 Midway 日志中的 SMTP 错误。