跳转至

Next.js

适用于 Next.js（Node.js 18+，App Router）应用的集成指南。Mailexam 通过 Nodemailer 及 Route Handler POST /api/mail/test 作为 SMTP 接入。

前置条件

  • Mailexam 账户，以及已创建并具备 SMTP 凭据的项目。
  • Node.js 18+ 与 npm。

从项目的欢迎邮件（或控制台）中复制：

  • YOUR_LOGIN — SMTP 登录名（例如 xxxxx）；
  • YOUR_PASSWORD — SMTP 密码（与登录名成对的唯一凭据）；
  • 主机 — YOUR_LOGIN.mailexam.cn（与登录名一致）。

1. 依赖

npx create-next-app@latest my-app
cd my-app
npm install nodemailer dotenv

package.json 最小依赖：

{
  "dependencies": {
    "dotenv": "^16.0.0",
    "next": "^15.0.0",
    "nodemailer": "^6.9.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

若使用 Docker 部署，在 next.config.js 中启用 standalone 输出：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
};

module.exports = nextConfig;

2. 环境变量

项目根目录的 .env 或 .env.local（勿将密码提交到 git）：

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

SMTP 主机：YOUR_LOGIN.mailexam.cn（GitHub 参考实现 中域名为 mailexam.io，请按欢迎邮件中的主机填写）。

Next.js 会在 Route Handler（服务端）中自动加载这些变量。

发件人地址

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

备选端口

MAILEXAM_PORT=587

传输配置：secure: false。

MAILEXAM_PORT=2525

MAILEXAM_PORT=465

传输配置：secure: true。

3. Nodemailer 传输

// mail.js
import 'dotenv/config';

import nodemailer from 'nodemailer';

function createTransport() {
  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,
    },
  });
}

export async function sendTest({ to, subject, text }) {
  const transport = createTransport();

  await transport.sendMail({
    from: process.env.MAIL_FROM || 'noreply@example.test',
    to: to || 'user@example.test',
    subject: subject || 'Next.js + Mailexam',
    text: text || 'Mailexam test from Next.js',
  });
}

4. Route Handler

// app/api/mail/test/route.js
import { sendTest } from '../../../../mail.js';

export async function POST(request) {
  try {
    const body = await request.json();
    const { to, subject, text, body: messageBody } = body ?? {};

    await sendTest({
      to,
      subject,
      text: text ?? messageBody,
    });

    return Response.json({ status: 'ok' });
  } catch (error) {
    return Response.json({ error: error.message }, { status: 500 });
  }
}

启动并验证：

npm run dev

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

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

完整示例见 Next.js 实现示例（GitHub）。

5. 本地开发与 CI

环境 建议
local .env.local 中配置 Mailexam 凭据
CI 在 GitLab CI/CD Variables 中设置 MAILEXAM_LOGIN、MAILEXAM_PASSWORD

.gitlab-ci.yml 示例：

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

集成测试后，通过 Mailexam API 验证投递。

6. 常见问题

连接超时 / 认证失败

  • 主机应为 {login}.mailexam.cn，用户名为邮件中的同一登录名。
  • 登录名与密码须为同一项目欢迎邮件中的成对凭据。

路由返回 404

  • 路径为 /api/mail/test（App Router），不是 /mail/test。

587 端口与 TLS

  • 587：secure: false（STARTTLS）。465：secure: true。

控制台中看不到邮件

  • 查看同一 Mailexam 项目的收件箱。
  • 检查 Route Handler 返回的 JSON 错误信息。

参见