stripe 的 custom_fields 不适用于商品变体管理与库存控制；正确做法是为每个 sku（如 t 恤的 s/m/l）创建独立的 product + price，并在自有系统中维护实时库存与预占逻辑。
stripe 的 custom_fields 不适用于商品变体管理与库存控制；正确做法是为每个 sku（如 t 恤的 s/m/l）创建独立的 product + price，并在自有系统中维护实时库存与预占逻辑。
在 Next.js 电商项目中集成 Stripe 时，一个常见误区是试图用 custom_fields 实现商品规格（如衣服尺码、颜色）选择和库存限制。但需明确：Stripe 的 custom_fields 是为收集支付后所需的附加元数据而设计的（例如 Discord 用户名、企业发票税号），而非替代商品变体建模或库存管理功能。 将尺码选择推迟到结账页不仅损害用户体验（用户应在商品页完成选型），更因 Stripe 缺乏原生库存能力，导致无法安全限制“Medium 尺码仅剩 30 件”这类业务规则。
✅ 正确架构：SKU 驱动 + 后端库存管控
应将每个可售组合视为独立的 Stock-Keeping Unit（SKU），并映射为 Stripe 中唯一的 Product 和 Price：
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
// 示例：为同一款 T 恤创建三个独立 Price（对应不同尺码）
const prices = await Promise.all([
stripe.prices.create({
product: 'prod_tshirt_basic', // 可复用同一 Product ID
unit_amount: 2999,
currency: 'usd',
nickname: 'T-Shirt - Small',
lookup_key: 'tshirt-small', // 关键！用于后端关联库存
}),
stripe.prices.create({
product: 'prod_tshirt_basic',
unit_amount: 2999,
currency: 'usd',
nickname: 'T-Shirt - Medium',
lookup_key: 'tshirt-medium',
}),
stripe.prices.create({
product: 'prod_tshirt_basic',
unit_amount: 2999,
currency: 'usd',
nickname: 'T-Shirt - Large',
lookup_key: 'tshirt-large',
}),
]);在前端商品页，用户选择尺码后，你应通过 lookup_key（如 'tshirt-medium'）查询对应 Price ID，并将其传入 Checkout Session：
// Next.js API Route: /api/create-checkout-session
export default async function handler(req, res) {
const { priceLookupKey, quantity } = req.body;
// ✅ 1. 校验库存（关键步骤！）
const stock = await db.inventory.findUnique({
where: { sku: priceLookupKey }
});
if (!stock || stock.quantity < quantity) {
return res.status(400).json({ error: 'Insufficient stock' });
}
// ✅ 2. 预占库存（防止超卖）
await db.inventory.update({
where: { sku: priceLookupKey },
data: { quantity: { decrement: quantity } }
});
// ✅ 3. 创建 Checkout Session（无 custom_fields）
const session = await stripe.checkout.sessions.create({
success_url: `${origin}/success?session_id={CHECKOUT_SESSION_ID}`,
cancel_url: origin + '/cart',
payment_method_types: ['card'],
mode: 'payment',
line_items: [{
price: await getPriceIdByLookupKey(priceLookupKey), // 根据 lookup_key 获取真实 Price ID
quantity,
}],
});
res.json({ url: session.url });
}⚠️ 必须注意的关键事项
- 库存一致性靠事务保障：校验与预占必须在数据库事务中完成（如 Prisma 的 transaction() 或 SQL BEGIN/COMMIT），避免并发请求导致超卖。
- 订单失败需回滚：监听 Stripe Webhook 事件 checkout.session.completed 成功后才确认发货；若用户放弃支付，需通过 checkout.session.expired 或定时任务释放预占库存。
- 禁止依赖 Stripe 端状态：Stripe 不提供库存字段、不支持 Price 级别库存标记，所有库存逻辑必须由你的应用完全托管。
- 自定义字段仍有其用武之地：例如收集「是否需要礼品包装」「配送备注」等不影响 SKU 和库存的非结构化信息，此时 custom_fields 才是合适选择。
总结
Stripe 是支付管道，不是商品目录或库存系统。要实现专业级变体与库存管理，唯一稳健路径是：
? 前端商品页完成规格选择 → ? 后端以 SKU 为粒度校验+预占库存 → ? 为每个 SKU 创建独立 Stripe Price → ? Checkout Session 仅传递已验证的 Price ID。
这套模式虽需额外开发，却能确保数据一致性、用户体验流畅性及业务扩展性——这正是构建可靠电商基础设施的基石。
