Next.js

Email checker for Next.js. Server-side and client-side email verification in React.

在 Next.js 应用中实现电子邮件验证,包括服务器端验证、API 路由和 React Server Components。

安装

npm install @emailverify/node

yarn add @emailverify/node

pnpm add @emailverify/node

环境设置

将您的 API 密钥添加到 .env.local：

EMAILVERIFY_API_KEY=bv_live_xxx

应用路由（Next.js 13+）

Server Action

为电子邮件验证创建服务器操作：

// app/actions/verify-email.ts
'use server';

import { EmailVerify } from '@emailverify/node';

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY!,
});

export async function verifyEmail(email: string) {
  try {
    const result = await client.verify(email);
    return {
      success: true,
      data: result,
    };
  } catch (error) {
    return {
      success: false,
      error: '验证失败',
    };
  }
}

使用 Server Action 的客户端组件

// app/components/signup-form.tsx
'use client';

import { useState, useTransition } from 'react';
import { verifyEmail } from '../actions/verify-email';

export function SignupForm() {
  const [email, setEmail] = useState('');
  const [verification, setVerification] = useState<any>(null);
  const [isPending, startTransition] = useTransition();

  const handleEmailBlur = () => {
    if (!email) return;

    startTransition(async () => {
      const result = await verifyEmail(email);
      setVerification(result);
    });
  };

  return (
    <form className="space-y-4">
      <div>
        <label htmlFor="email" className="block text-sm font-medium">
          电子邮件
        </label>
        <input
          id="email"
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          onBlur={handleEmailBlur}
          className="mt-1 block w-full rounded-md border-gray-300 shadow-sm"
        />

        {isPending && (
          <p className="text-sm text-gray-500 mt-1">验证中...</p>
        )}

        {verification?.data?.status === 'valid' && (
          <p className="text-sm text-green-600 mt-1">✓ 电子邮件已验证</p>
        )}

        {verification?.data?.status === 'invalid' && (
          <p className="text-sm text-red-600 mt-1">
            请输入有效的电子邮件
          </p>
        )}

        {verification?.data?.result?.disposable && (
          <p className="text-sm text-yellow-600 mt-1">
            请使用永久电子邮件
          </p>
        )}
      </div>

      <button
        type="submit"
        disabled={isPending || verification?.data?.status !== 'valid'}
        className="w-full py-2 px-4 bg-blue-600 text-white rounded-md disabled:opacity-50"
      >
        注册
      </button>
    </form>
  );
}

API 路由处理器

// app/api/verify-email/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { EmailVerify } from '@emailverify/node';

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY!,
});

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const { email } = body;

    if (!email) {
      return NextResponse.json(
        { error: '电子邮件是必需的' },
        { status: 400 }
      );
    }

    const result = await client.verify(email);
    return NextResponse.json(result);
  } catch (error) {
    console.error('验证错误:', error);
    return NextResponse.json(
      { error: '验证失败' },
      { status: 500 }
    );
  }
}

React Server Component

在呈现之前服务器端验证电子邮件：

// app/user/[id]/page.tsx
import { EmailVerify } from '@emailverify/node';
import { notFound } from 'next/navigation';

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY!,
});

async function getUser(id: string) {
  // 从您的数据库获取用户
  const user = await db.users.findUnique({ where: { id } });
  return user;
}

export default async function UserPage({ params }: { params: { id: string } }) {
  const user = await getUser(params.id);

  if (!user) {
    notFound();
  }

  // 如果尚未验证，请验证电子邮件
  let emailVerification = null;
  if (!user.emailVerified) {
    emailVerification = await client.verify(user.email);
  }

  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>

      {emailVerification && (
        <div className="mt-4">
          <h2>电子邮件状态</h2>
          <p>状态: {emailVerification.status}</p>
          <p>分数: {emailVerification.score}</p>
        </div>
      )}
    </div>
  );
}

Pages Router (Next.js 12)

API Route

// pages/api/verify-email.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { EmailVerify } from '@emailverify/node';

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY!,
});

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: '方法不允许' });
  }

  const { email } = req.body;

  if (!email) {
    return res.status(400).json({ error: '电子邮件是必需的' });
  }

  try {
    const result = await client.verify(email);
    return res.json(result);
  } catch (error) {
    console.error('验证错误:', error);
    return res.status(500).json({ error: '验证失败' });
  }
}

getServerSideProps

在 SSR 期间验证电子邮件：

// pages/user/[id].tsx
import { GetServerSideProps } from 'next';
import { EmailVerify } from '@emailverify/node';

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY!,
});

interface Props {
  user: User;
  emailVerification: VerificationResult | null;
}

export const getServerSideProps: GetServerSideProps<Props> = async (context) => {
  const { id } = context.params!;

  const user = await getUser(id as string);

  if (!user) {
    return { notFound: true };
  }

  let emailVerification = null;
  if (!user.emailVerified) {
    try {
      emailVerification = await client.verify(user.email);
    } catch (error) {
      console.error('验证失败:', error);
    }
  }

  return {
    props: {
      user,
      emailVerification,
    },
  };
};

export default function UserPage({ user, emailVerification }: Props) {
  return (
    <div>
      <h1>{user.name}</h1>
      {emailVerification && (
        <p>电子邮件状态: {emailVerification.status}</p>
      )}
    </div>
  );
}

表单处理模式

使用 useFormState（React 19）

// app/components/form-with-state.tsx
'use client';

import { useFormState, useFormStatus } from 'react-dom';
import { signupAction } from '../actions/signup';

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button type="submit" disabled={pending}>
      {pending ? '提交中...' : '注册'}
    </button>
  );
}

export function SignupFormWithState() {
  const [state, formAction] = useFormState(signupAction, {
    success: false,
    errors: {},
  });

  return (
    <form action={formAction}>
      <div>
        <input type="email" name="email" required />
        {state.errors?.email && (
          <p className="text-red-600">{state.errors.email}</p>
        )}
      </div>

      <div>
        <input type="text" name="name" required />
        {state.errors?.name && (
          <p className="text-red-600">{state.errors.name}</p>
        )}
      </div>

      <SubmitButton />

      {state.success && (
        <p className="text-green-600">帐户创建成功！</p>
      )}
    </form>
  );
}

// app/actions/signup.ts
'use server';

import { EmailVerify } from '@emailverify/node';
import { z } from 'zod';

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY!,
});

const signupSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
});

export async function signupAction(
  prevState: any,
  formData: FormData
) {
  const rawData = {
    email: formData.get('email') as string,
    name: formData.get('name') as string,
  };

  // Validate schema
  const parsed = signupSchema.safeParse(rawData);
  if (!parsed.success) {
    return {
      success: false,
      errors: parsed.error.flatten().fieldErrors,
    };
  }

  // 验证电子邮件
  const verification = await client.verify(parsed.data.email);

  if (verification.status === 'invalid') {
    return {
      success: false,
      errors: { email: ['请输入有效的电子邮件地址'] },
    };
  }

  if (verification.result.disposable) {
    return {
      success: false,
      errors: { email: ['不允许使用一次性电子邮件'] },
    };
  }

  // 在数据库中创建用户
  await createUser(parsed.data);

  return { success: true, errors: {} };
}

使用 React Hook Form

// app/components/react-hook-form-example.tsx
'use client';

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const schema = z.object({
  email: z.string().email('无效的电子邮件'),
  password: z.string().min(8, '密码至少需要 8 个字符'),
});

type FormData = z.infer<typeof schema>;

export function SignupFormHookForm() {
  const {
    register,
    handleSubmit,
    setError,
    formState: { errors, isSubmitting },
  } = useForm<FormData>({
    resolver: zodResolver(schema),
  });

  const onSubmit = async (data: FormData) => {
    // 验证电子邮件
    const response = await fetch('/api/verify-email', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: data.email }),
    });

    const verification = await response.json();

    if (verification.status === 'invalid') {
      setError('email', {
        type: 'manual',
        message: '请输入有效的电子邮件地址',
      });
      return;
    }

    // 继续注册
    console.log('提交:', data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
      <div>
        <input
          type="email"
          {...register('email')}
          className="w-full p-2 border rounded"
        />
        {errors.email && (
          <p className="text-red-600 text-sm">{errors.email.message}</p>
        )}
      </div>

      <div>
        <input
          type="password"
          {...register('password')}
          className="w-full p-2 border rounded"
        />
        {errors.password && (
          <p className="text-red-600 text-sm">{errors.password.message}</p>
        )}
      </div>

      <button
        type="submit"
        disabled={isSubmitting}
        className="w-full py-2 bg-blue-600 text-white rounded disabled:opacity-50"
      >
        {isSubmitting ? '验证中...' : '注册'}
      </button>
    </form>
  );
}

中间件验证

在 Next.js 中间件中验证电子邮件：

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export async function middleware(request: NextRequest) {
  // 仅在注册路由上运行
  if (request.nextUrl.pathname !== '/api/signup') {
    return NextResponse.next();
  }

  const body = await request.json();
  const { email } = body;

  if (email) {
    // 在处理注册之前验证电子邮件
    const verifyResponse = await fetch(
      'https://api.emailverify.ai/v1/verify',
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.EMAILVERIFY_API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ email }),
      }
    );

    const verification = await verifyResponse.json();

    if (verification.status === 'invalid') {
      return NextResponse.json(
        { error: '无效的电子邮件地址' },
        { status: 400 }
      );
    }
  }

  return NextResponse.next();
}

export const config = {
  matcher: '/api/signup',
};

缓存策略

路由处理器缓存

// app/api/verify-email/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { EmailVerify } from '@emailverify/node';

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY!,
});

// 内存缓存（生产环境中使用 Redis）
const cache = new Map<string, { result: any; timestamp: number }>();
const CACHE_DURATION = 3600000; // 1 小时

export async function POST(request: NextRequest) {
  const { email } = await request.json();

  // 检查缓存
  const cached = cache.get(email);
  if (cached && Date.now() - cached.timestamp < CACHE_DURATION) {
    return NextResponse.json(cached.result, {
      headers: { 'X-Cache': 'HIT' },
    });
  }

  // 验证电子邮件
  const result = await client.verify(email);

  // 缓存结果
  cache.set(email, { result, timestamp: Date.now() });

  return NextResponse.json(result, {
    headers: { 'X-Cache': 'MISS' },
  });
}

Redis 缓存（生产环境）

// lib/verify-with-cache.ts
import { Redis } from '@upstash/redis';
import { EmailVerify } from '@emailverify/node';

const redis = Redis.fromEnv();
const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY!,
});

export async function verifyEmailWithCache(email: string) {
  const cacheKey = `email-verify:${email}`;

  // 检查缓存
  const cached = await redis.get(cacheKey);
  if (cached) {
    return { ...cached, fromCache: true };
  }

  // 验证电子邮件
  const result = await client.verify(email);

  // 缓存 24 小时
  await redis.setex(cacheKey, 86400, result);

  return { ...result, fromCache: false };
}

批量验证

使用 API 路由的后台任务

// app/api/verify-bulk/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { EmailVerify } from '@emailverify/node';

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY!,
});

export async function POST(request: NextRequest) {
  const { emails, webhookUrl } = await request.json();

  // 提交批量任务
  const job = await client.verifyBulk(emails, {
    webhookUrl: webhookUrl || `${process.env.NEXT_PUBLIC_URL}/api/webhook/bulk-complete`,
  });

  return NextResponse.json(job);
}

// 完成的 Webhook 处理器
// app/api/webhook/bulk-complete/route.ts
export async function POST(request: NextRequest) {
  const event = await request.json();

  if (event.event === 'bulk.completed') {
    // 处理已完成的任务
    await processCompletedJob(event.data.job_id);
  }

  return NextResponse.json({ received: true });
}

错误处理

全局错误处理器

// lib/emailverify.ts
import { EmailVerify } from '@emailverify/node';

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY!,
});

export async function verifyEmailSafe(email: string) {
  try {
    const result = await client.verify(email);
    return { success: true, data: result };
  } catch (error: any) {
    // 记录错误以供监控
    console.error('电子邮件验证失败:', {
      email,
      error: error.message,
      code: error.code,
    });

    // 返回优雅的回退方案
    if (error.code === 'RATE_LIMIT_EXCEEDED') {
      return {
        success: false,
        error: '超过速率限制',
        retryAfter: error.retryAfter,
      };
    }

    if (error.code === 'INSUFFICIENT_CREDITS') {
      return {
        success: false,
        error: '服务暂时不可用',
      };
    }

    return {
      success: false,
      error: '验证失败',
    };
  }
}

TypeScript 配置

为了获得完整的类型安全，扩展您的类型：

// types/emailverify.ts
import type { VerificationResult } from '@emailverify/node';

export interface VerifyEmailResponse {
  success: boolean;
  data?: VerificationResult;
  error?: string;
  fromCache?: boolean;
}

export interface SignupFormState {
  success: boolean;
  errors: {
    email?: string[];
    name?: string[];
  };
}

最佳实践

1. 始终进行服务器端验证

// ✅ 好 - 服务器端验证
export async function signupAction(data: FormData) {
  const email = data.get('email') as string;
  const verification = await verifyEmail(email);
  // ...
}

// ❌ 坏 - 仅客户端验证可能被绕过

2. 处理所有状态

function EmailStatus({ verification }: { verification: any }) {
  if (verification.isLoading) return <Loading />;
  if (verification.error) return <ErrorMessage />;
  if (!verification.data) return null;

  switch (verification.data.status) {
    case 'valid':
      return <ValidBadge />;
    case 'invalid':
      return <InvalidMessage />;
    case 'unknown':
      return <UnknownWarning />;
    case 'accept_all':
      return <CatchAllWarning />;
    default:
      return null;
  }
}

3. 不要阻止用户流程

// 允许提交但警告用户
<button
  type="submit"
  disabled={isSubmitting}
>
  {verification?.status === 'invalid'
    ? '仍然提交'
    : '提交'}
</button>