本文详解如何在 Stripe Webhook 中正确通过邮箱查询客户，解决 checkout.session.customer 为 null 的常见问题，并提供安全、规范的 customers->search() 调用方式与关键注意事项。
本文详解如何在 stripe webhook 中正确通过邮箱查询客户，解决 `checkout.session.customer` 为 `null` 的常见问题，并提供安全、规范的 `customers->search()` 调用方式与关键注意事项。
在处理 Stripe Checkout Webhook 时，开发者常遇到 checkout.session 对象中 customer 字段为 null 的情况——这并非异常，而是由 Checkout Session 的配置决定的。当未显式启用 customer_creation: "always" 或 customer: "existing_customer_id" 参数时，Stripe 默认不会复用或创建客户对象，导致该字段缺失。此时，需通过客户邮箱反向查找已存在的 Customer 记录，而 customers->search() 是官方推荐的高效方式。
但需特别注意：Stripe 的搜索查询语法对字符串值要求严格——邮箱必须用单引号包裹（'），且不能包含 HTML 标签或编码字符。原始代码中 $email 变量实际嵌入了 Cloudflare 邮箱保护的 标签（含 data-cfemail 属性），这会导致查询完全失效。此外，直接拼接字符串存在注入风险，应先清理并转义输入。
✅ 正确做法如下：
use Stripe\StripeClient;
$stripe = new StripeClient('sk_test_...'); // 请替换为你的测试密钥
// 1. 从 session 提取原始邮箱（确保无 HTML/JS 干扰）
$email = $session->customer_details->email ?? null;
if (!$email || !filter_var($email, FILTER_VALIDATE_EMAIL)) {
throw new InvalidArgumentException('Invalid or missing email');
}
// 2. 构造符合 Stripe 搜索语法的 query 字符串（单引号包裹，不加额外转义）
$query = "email:'{$email}'";
// 3. 执行搜索（支持分页，此处取首条匹配结果）
try {
$searchResult = $stripe->customers->search([
'query' => $query,
'limit' => 1,
]);
$customer = $searchResult->data[0] ?? null;
if ($customer) {
echo "Found customer: {$customer->id} ({$customer->email})";
} else {
echo "No customer found for email: {$email}";
}
} catch (\Stripe\Exception\ApiErrorException $e) {
error_log("Stripe search failed: " . $e->getMessage());
// 处理 API 错误（如权限不足、无效 query 等）
}⚠️ 关键注意事项：
立即学习“PHP免费学习笔记（深入）”；
- 永远不要手动拼接 HTML 邮箱字段：Webhook 收到的 session.customer_details.email 是纯文本，若前端传入的是被 Cloudflare 或其他服务混淆的 HTML 片段，需在服务端清洗（可用 strip_tags() + trim()）；
- 单引号是必需语法：email:'user@example.com' ✅；email:user@example.com ❌；email:"user@example.com" ❌；
- 区分测试/生产环境密钥：Webhook 必须使用对应环境的 Secret Key（sk_test_ / sk_live_），且确保 API 权限已启用 customers:read；
- 性能与可靠性：search 接口基于异步索引，新建客户后可能存在毫秒级延迟；如需强一致性，建议在创建客户时记录 ID 到本地数据库，并在 Checkout 中通过 customer: "cus_..." 显式关联。
总结：checkout.session.customer 为 null 是可预期行为，合理利用 customers->search() 并严格遵循查询语法，即可稳定获取客户上下文。务必以 customer_details.email 为唯一可信来源，并做好输入校验与错误兜底。
