1. 批量导入邮箱时，为什么去重和格式校验总在踩坑
做用户系统或者 CRM 导入功能时，邮箱字段几乎是最容易出问题的地方。运营给过来一份 Excel，几千行联系人，邮箱列里混着逗号分隔的多个地址、大小写不一致的重复项、还有abc@这种明显残缺的格式。如果直接INSERT进库，轻则唯一索引报错中断整批导入，重则脏数据进库，后面发营销邮件时退信率飙升。
我处理过的一个典型场景是这样的：后台支持一次粘贴多个邮箱，用英文逗号分隔，比如a@x.com,b@x.com,a@X.com。业务要求同一联系人下邮箱不能重复，同时每个邮箱必须符合基本格式。最初的代码就是拿到字符串直接explode，然后array_unique判断数量，再用一条正则逐个匹配。看起来没问题，但实际跑起来有三个坑：
第一，array_unique是区分大小写的，a@x.com和A@x.com会被当成两个不同的值，去重失效。第二，正则写得太宽松或者太严格，宽松了a@b能过，严格了a+b@x.com这种合法地址被拦。第三，批量导入时如果逐行调用校验函数，几千条数据会拖慢整个请求，而且错误信息只能抛异常中断，没法一次性告诉运营"第 37 行、第 152 行有问题"。
所以真正可用的方案要解决三件事：归一化后再去重、格式校验规则要贴合实际业务、批量场景下要能收集所有错误而不是遇错即停。这篇就围绕这三个点，给出可以直接复制的 PHP 函数、去重 SQL，以及如何把校验逻辑通过 TaoToken 的统一 Key 通道接进现有流程，让格式校验和后续的 AI 辅助清洗走同一个入口。
适合谁看：正在写用户导入、CRM 同步、邮件列表清洗的 PHP 后端；或者你手上有一堆历史邮箱数据，想批量过一遍格式和重复检查。下面从环境准备开始，一步步来。
2. TaoToken 统一 Key 通道准备与 PHP 环境接入
在动手写校验函数之前，先把"通道"这件事说清楚。很多团队的邮箱清洗流程里，格式校验只是第一步，后面往往还要接一个 AI 接口做更智能的判断，比如识别一次性邮箱域名、判断企业邮箱还是个人邮箱、甚至从一段混乱文本里抽取邮箱。如果每个服务都单独配一套 Key 和 Base URL，维护起来很烦。TaoToken 的思路是提供一个统一的 API 通道，模型对话、编码辅助、密钥管理都在同一个控制台里，PHP 侧只需要认一个 Base URL 和一把 Key。
你需要先拿到两样东西：API Key和Base URL。Key 在控制台的 API Keys 页面创建，Base URL 统一用https://taotoken.net/api。注意这里不要带任何查询参数，就是干净的域名加路径。创建 Key 的时候建议按用途命名，比如email-clean-prod，方便后面轮换和排查。
PHP 环境这边，推荐 PHP 7.4 以上，需要开启curl和json扩展。检查一下：
php -m | grep -E 'curl|json'如果两个都输出，说明环境没问题。接下来把配置写进一个独立的配置文件，不要硬编码在业务代码里。我用一个config/taotoken.php来存：
<?php // config/taotoken.php return [ 'base_url' => 'https://taotoken.net/api', 'api_key' => getenv('TAOTOKEN_API_KEY') ?: 'sk-你的实际Key', 'model' => 'claude-3-5-sonnet', 'timeout' => 30, ];把 Key 放在环境变量里是更稳妥的做法，本地开发可以用.env加载。如果你用的是 Laravel，直接进config/services.php加一段也行。核心就是三件套：Base URL + Key + Model ID，后面所有请求都基于这三个值。
这里要提醒一句：TaoToken 是合规的 API 聚合通道，不要把它理解成什么特殊网络工具，它就是一个标准的 HTTP 接口，你用 curl 或者 Guzzle 正常发请求就行。接入文档在https://taotoken.net/doc，里面有各语言的示例，PHP 的 curl 写法可以直接参考。
配置好之后，先写一个最小的连通性测试，确认 Key 有效：
<?php $config = require 'config/taotoken.php'; $ch = curl_init($config['base_url'] . '/v1/models'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . $config['api_key'], 'Content-Type: application/json', ], CURLOPT_TIMEOUT => 10, ]); $response = curl_exec($ch); $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo "HTTP: $httpCode\n"; echo $response;如果返回 200 并且能看到模型列表，说明通道通了。如果返回 401，检查 Key 有没有复制完整、有没有多余空格。这一步过了，再往下写校验逻辑。
3. 可复制的 PHP 邮箱校验函数与去重 SQL 配置
这一节是核心，直接给能用的代码。先解决格式校验和归一化，再解决去重，最后给批量导入的 SQL 策略。
3.1 归一化 + 格式校验函数
关键点是先归一化再去重。归一化做两件事：去首尾空格、域名部分转小写（本地部分按 RFC 是区分大小写的，但实际业务里几乎都按不区分处理，这里统一转小写更符合直觉）。
<?php /** * 归一化单个邮箱 */ function normalizeEmail(string $email): string { $email = trim($email); // 去掉可能包裹的尖括号，如 <a@x.com> $email = trim($email, "<> \t\n\r\0\x0B"); return strtolower($email); } /** * 校验单个邮箱格式 * 返回 true 或错误原因字符串 */ function validateEmail(string $email) { if ($email === '') { return '邮箱为空'; } if (strlen($email) > 254) { return '邮箱长度超过254'; } // 本地部分不允许连续点、首尾点 if (!preg_match('/^[a-z0-9!#$%&\'*+\/=?^_`{|}~.-]+@[a-z0-9-]+(\.[a-z0-9-]+)+$/', $email)) { return '格式不正确'; } if (strpos($email, '..') !== false) { return '包含连续点'; } [$local, $domain] = explode('@', $email, 2); if ($local === '' || $domain === '') { return '本地部分或域名缺失'; } if (strpos($domain, '.') === false) { return '域名缺少点号'; } return true; }这个正则比 excerpt 里那条更稳：它要求域名至少有一个点，本地部分允许+和常见符号，同时单独拦截连续点。实测下来，a+b@x.com、first.last@sub.domain.com都能过，a@b、a@@x.com、a..b@x.com会被拦。
3.2 批量校验并收集所有错误
批量场景不要遇错就抛异常，而是返回一个错误列表，让调用方决定怎么展示。
<?php /** * 批量校验，返回 [合法邮箱数组, 错误列表] */ function validateEmailBatch(array $rawEmails): array { $valid = []; $errors = []; $seen = []; foreach ($rawEmails as $index => $raw) { $email = normalizeEmail($raw); if ($email === '') { continue; // 空行跳过，不算错误 } $result = validateEmail($email); if ($result !== true) { $errors[] = ['row' => $index + 1, 'email' => $raw, 'reason' => $result]; continue; } if (isset($seen[$email])) { $errors[] = ['row' => $index + 1, 'email' => $raw, 'reason' => '重复邮箱']; continue; } $seen[$email] = true; $valid[] = $email; } return [$valid, $errors]; }用法：
$input = "a@x.com, B@X.com ,a@x.com, bad@@x.com, c@y.com"; $list = array_map('trim', explode(',', $input)); [$valid, $errors] = validateEmailBatch($list); print_r($valid); print_r($errors);预期输出：$valid是['a@x.com', 'c@y.com']，$errors里会有B@X.com被标记为重复（因为归一化后和a@x.com相同）、bad@@x.com格式不正确。这样运营能一次性看到所有问题行。
3.3 去重 SQL 与唯一索引策略
数据库层面也要兜底。假设表结构是contacts(id, user_id, email)，先建唯一索引，注意 MySQL 默认排序规则utf8mb4_general_ci本身就不区分大小写，所以A@x.com和a@x.com在唯一索引下会冲突，这正好符合我们的归一化预期。
ALTER TABLE contacts ADD UNIQUE KEY uk_user_email (user_id, email);批量插入时用INSERT ... ON DUPLICATE KEY UPDATE或者INSERT IGNORE来跳过重复。如果要在插入前查重，用这条：
SELECT email, COUNT(*) AS cnt FROM contacts WHERE user_id = ? GROUP BY email HAVING cnt > 1;对于导入前的预检，把待导入邮箱和库里已有邮箱做交集：
SELECT email FROM contacts WHERE user_id = ? AND email IN (:emailList);在 PHP 里用 PDO 绑定数组时，记得动态生成占位符。这里给一个可复制的片段：
<?php function findExistingEmails(PDO $pdo, int $userId, array $emails): array { if (empty($emails)) { return []; } $placeholders = implode(',', array_fill(0, count($emails), '?')); $sql = "SELECT email FROM contacts WHERE user_id = ? AND email IN ($placeholders)"; $stmt = $pdo->prepare($sql); $stmt->execute(array_merge([$userId], $emails)); return $stmt->fetchAll(PDO::FETCH_COLUMN); }这样导入流程就是：先validateEmailBatch过滤格式和批内重复，再findExistingEmails过滤库内重复，最后批量插入。三层防护下来，脏数据基本进不去。
3.4 把 AI 辅助清洗接进同一通道
如果你还想做更进一步的清洗，比如识别test@mailinator.com这类一次性邮箱，或者从一段自由文本里抽取邮箱，可以走 TaoToken 的模型对话接口。配置片段如下，注意 Base URL 和 Key 复用前面的：
<?php function askTaoToken(string $prompt): string { $config = require 'config/taotoken.php'; $payload = json_encode([ 'model' => $config['model'], 'messages' => [ ['role' => 'user', 'content' => $prompt], ], ], JSON_UNESCAPED_UNICODE); $ch = curl_init($config['base_url'] . '/v1/chat/completions'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => $payload, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . $config['api_key'], 'Content-Type: application/json', ], CURLOPT_TIMEOUT => $config['timeout'], ]); $response = curl_exec($ch); $err = curl_error($ch); curl_close($ch); if ($err) { throw new RuntimeException('请求失败: ' . $err); } $data = json_decode($response, true); return $data['choices'][0]['message']['content'] ?? ''; }调用示例：把一批可疑邮箱丢进去，让它返回哪些是一次性域名。这样格式校验用本地函数（快、免费），语义判断用模型（准、按需），两者通过同一个 Key 通道管理，省去多套凭证的麻烦。
4. 验证请求与批量清洗的成功结果
写完代码必须验证，不然上线就是事故。分三步验证：单元级、批量级、接口级。
第一步，单元验证。准备一组边界用例，直接跑validateEmail：
<?php $cases = [ 'a@x.com' => true, 'A@X.COM' => true, 'a+b@x.com' => true, 'first.last@x.co' => true, 'a@b' => false, 'a@@x.com' => false, 'a..b@x.com' => false, '' => false, 'a@x.com ' => true, // 归一化后 ]; foreach ($cases as $input => $expected) { $normalized = normalizeEmail($input); $result = validateEmail($normalized); $ok = ($result === true) === $expected ? 'PASS' : 'FAIL'; echo sprintf("%-20s => %-6s [%s]\n", $input, $result === true ? 'valid' : $result, $ok); }预期所有行都是 PASS。如果a@b被判为 valid，说明正则里域名点号判断没生效，回去检查strpos($domain, '.')那段。
第二步，批量验证。用 1000 行模拟数据跑一遍，看耗时和错误收集是否完整：
<?php $emails = []; for ($i = 0; $i < 1000; $i++) { $emails[] = "user{$i}@example.com"; } // 故意插入重复和错误 $emails[] = 'user1@example.com'; $emails[] = 'bad@@example.com'; $start = microtime(true); [$valid, $errors] = validateEmailBatch($emails); $cost = round((microtime(true) - $start) * 1000, 2); echo "合法: " . count($valid) . " 条\n"; echo "错误: " . count($errors) . " 条\n"; echo "耗时: {$cost} ms\n";预期：合法 1000 条，错误 2 条（一条重复、一条格式错），耗时在几十毫秒级别。如果耗时超过 500ms，检查是不是在循环里做了数据库查询。
第三步，接口验证。如果你把校验封装成了 HTTP 接口，用 curl 打一下：
curl -X POST https://your-domain.com/api/email/validate \ -H "Content-Type: application/json" \ -d '{"emails":["a@x.com","A@X.com","bad@@x.com"]}'预期返回：
{ "valid": ["a@x.com"], "errors": [ {"row": 2, "email": "A@X.com", "reason": "重复邮箱"}, {"row": 3, "email": "bad@@x.com", "reason": "格式不正确"} ] }看到这个结构，说明整条链路通了。数据库侧再跑一次findExistingEmails，确认库内重复也能被识别。
5. 本篇常见报错排查：401、local proxy failed、reading choices
实际接入和运行过程中，报错集中在几个地方。下面按真实错误信息对照排查。
401 Unauthorized。最常见。原因通常是 Key 没带、带错、或者带了多余空格。检查Authorization头是不是Bearer sk-xxx格式，中间一个空格。另外确认 Key 没有过期，控制台里可以重新生成。还有一种情况是把 Base URL 写成了带路径的形式，比如https://taotoken.net/api/v1，然后又拼了/v1/chat/completions，变成/api/v1/v1/...，虽然不一定 401，但会 404。Base URL 就用https://taotoken.net/api，路径在代码里拼。
local proxy failed。这个报错通常出现在你本地配了 HTTP 代理，但代理没启动或者端口不对。PHP 的 curl 会读取环境变量http_proxy/https_proxy。检查一下：
env | grep -i proxy如果有值但代理不可用，临时清掉再跑：
unset http_proxy https_proxy或者在 curl 里显式设置CURLOPT_PROXY => ''。注意这里说的是本地开发环境的代理配置问题，不是让你去搞什么网络工具，纯粹是排查环境变量干扰。
reading choices 相关报错。典型信息是Cannot read properties of undefined (reading 'choices')或者 PHP 侧$data['choices']为 null。这说明响应体不是预期的 JSON 结构。先打印原始响应：
var_dump($response);常见原因：返回的是错误 JSON（比如{"error":{"message":"..."}}），或者返回了 HTML（比如网关错误页）。如果是错误 JSON，看error.message里的具体原因。如果是 HTML，检查 URL 是不是拼错了。还有一种情况是json_decode失败但没检查，导致$data是 null，访问$data['choices']就报错。加一层判断：
$data = json_decode($response, true); if (!is_array($data) || !isset($data['choices'][0]['message']['content'])) { throw new RuntimeException('响应结构异常: ' . substr($response, 0, 200)); }OAuth 相关报错。如果你用的是 Claude Code 或者某些需要 OAuth 授权的客户端，可能会遇到 token 过期。这类客户端一般有自己的登录流程，重新走一遍授权即可。注意 OAuth 的 token 和 API Key 是两套东西，不要混用。API 调用走Authorization: Bearer，OAuth 走Authorization: Bearer <oauth_token>但获取方式不同。排查时先确认你用的是哪种认证方式。
数据库唯一索引冲突。报Duplicate entry 'a@x.com' for key 'uk_user_email'。这说明你的应用层去重没拦住，或者并发导入时两个请求同时插入。解决办法：应用层用INSERT IGNORE或ON DUPLICATE KEY UPDATE，并且确保归一化在插入前完成。如果业务允许覆盖，用ON DUPLICATE KEY UPDATE updated_at = NOW()。
正则匹配性能问题。如果邮箱列表特别大（十万级），逐条preg_match会慢。可以先用filter_var($email, FILTER_VALIDATE_EMAIL)做快速初筛，再用自定义正则做业务规则补充。filter_var是 C 实现，比 PHP 正则快不少。
6. 把校验服务接进现有流程的落地建议
代码写完了，怎么接进现有流程才是关键。给几个实操建议。
第一，校验前置。在 Controller 接收参数后、写库前就调用validateEmailBatch，不要等到 Model 层。这样错误能在接口层直接返回给前端，运营看到的是"第 3 行格式错误"，而不是数据库抛出的异常堆栈。
第二，错误信息结构化。返回给前端的错误列表带上行号、原始值、原因，前端可以高亮显示。别只返回一个"邮箱格式不正确"，运营得自己一行行找。
第三，批量导入分批处理。如果一次导入上万条，不要在一个请求里全跑完。按 500 条一批，分批校验、分批插入，每批返回进度。这样即使中途失败，也能知道处理到哪了。
第四，Key 管理。TaoToken 的 Key 建议按环境分开，开发、测试、生产各一把。控制台里可以随时吊销和重建。不要把 Key 提交到 Git，用环境变量或者密钥管理服务。
第五，日志留痕。每次批量清洗记录：输入条数、合法条数、错误条数、耗时。出问题时能快速定位是哪一批数据、哪个规则出的问题。
如果你后面还要做更复杂的清洗，比如根据邮箱域名判断公司、从邮件正文抽取联系人，可以走 Coding Plan 把这类任务做成定时脚本，复用同一套 Key 和 Base URL。接入文档里有完整的参数说明，模型对话页面可以直接测试 prompt 效果，确认没问题再写进代码。
最后说一个我踩过的坑：早期版本我在validateEmailBatch里对每个邮箱都查一次数据库看是否重复，1000 条数据查了 1000 次，接口响应 8 秒。后来改成先收集全部邮箱，用一条IN查询批量取回已有记录，再在内存里做差集，耗时降到 200ms 以内。批量场景下，能一次查完的绝不放循环里，这个原则比任何优化技巧都管用。
