常见问题

事件没有出现

现象： 完成了测试购买，但仪表盘中没有显示任何事件。

按顺序检查：

1. Webhook URL — 在 Money Fast 中进入网站 设置 > 连接，确认 Webhook URL 正确。
2. 签名密钥 — 确保签名密钥匹配。密钥错误会导致签名验证失败（HTTP 401）。
3. Webhook 日志 — 检查 Stripe 的 Webhook 日志，查看是否有投递错误（非 200 响应）。
4. 网站状态 — 确保你的网站在 Money Fast 设置中是 运行中（未被停用）。
5. 事件类型 — 如果使用手动 Webhook 方式，确认已勾选所有 所需事件。

归因数据为空

现象： 订单出现在仪表盘中，但来源、设备、着陆页等归因字段为空。

可能的原因：

1. 脚本未安装或 ID 不匹配 — 你的网站上必须安装正确的 追踪脚本，且 data-website-id 必须与当前网站匹配。在设置中使用 归因脚本 > 检测 按钮验证 — 会同时检查脚本是否存在以及 website ID 是否正确。
2. Metadata 未传递 — 必须将归因 Cookie 数据作为结账 metadata 传递。参见 归因追踪 获取代码示例。
3. 订阅 metadata 缺失 — 对于 Stripe 订阅，Checkout Session 上的 metadata 不会自动传递到订阅对象。你必须同时设置 subscription_data.metadata，否则续费事件将缺失归因数据。
4. Cookie 被拦截 — 如果访客浏览器屏蔽了 Cookie 或使用了隐私插件，_moneyfast Cookie 可能无法设置。

重复订单

现象： 同一笔订单出现了多次。

正常情况下不会发生。 Money Fast 通过 (websiteId, provider, providerOrderId) 去重。如果看到重复，请检查：

1. 多个 Webhook 端点 — 确保 Stripe 中没有多个 Webhook 端点指向同一个 Money Fast 网站。每个网站只应有一个端点。
2. 导入和 Webhook 重叠 — 这是安全的。导入的记录和 Webhook 记录会自动去重，同一笔订单不会被计算两次。

导入卡在"导入中"

现象： 导入状态长时间显示"导入中..."，没有完成。

1. 等待最多 30 分钟 — 大量数据导入需要时间，进度指示器会显示当前阶段。
2. 自动恢复 — 如果导入超过 30 分钟仍未完成，Money Fast 会自动将其标记为失败，你可以重试。
3. 重试 — 前往 设置 > 导入，再次点击导入。已有记录会被跳过，因此重试是安全的。

API Key 验证失败

现象： 保存 Stripe Restricted Key 时报错。

1. Key 格式 — Key 应以 rk_live_（生产环境）或 rk_test_（测试环境）开头。
2. 权限 — 确保 Key 拥有所有 所需权限，特别是 Webhooks: Write。
3. Key 状态 — 在 Stripe 控制台中确认 Key 处于启用状态，未被撤销。

Webhook 返回 404

现象： Stripe 的 Webhook 投递日志显示 404 错误。

1. 网站已删除 — Webhook 端点引用的网站已从 Money Fast 中删除。
2. URL 已变更 — 如果你重新创建了网站，Webhook URL（使用网站 ID）已改变。需要在 Stripe 中更新端点。

数据与 Stripe 不一致

现象： Money Fast 中的收入数字与 Stripe 控制台不一致。

1. 对比正确的指标 — Money Fast 的 总收入（All Time Revenue） 对应 Stripe 的 总额（Gross volume），即所有成功收款的支付总额（包含已退款和争议的交易，未扣除手续费）。时段收入（如"最近 30 天总收入"）只计算当前状态为已支付的订单。
2. 货币转换 — Money Fast 优先使用 Stripe 结算数据（balance transaction）进行多币种换算，无结算数据时回退到汇率 API。建议将网站的货币设置与 Stripe 账户的结算货币保持一致以获得最佳精度。
3. 日期范围 — 确保比较的是相同的日期范围和时区。Money Fast 使用你为网站配置的时区。
4. 历史数据 — 如果你没有导入历史数据，只有 Webhook 连接后的事件会被追踪。使用导入页面导入 Checkout Sessions（首购）、Invoices（续费）和 Subscriptions（订阅状态）。