从哪里开始排查
安装之后数字不对，先按症状打开下面的一篇，按检查顺序做完再联系支持。采集请求返回 202 只表示采集端收下了这次请求，不表示事件已经进报表。
| 症状 | 打开 | 先确认的事实 |
|---|---|---|
| 实时或报表里看不到访问 | 统计无数据 | 脚本是否发出采集请求；域名、排除规则、额度和暂停是否把事件丢掉 |
| 同一次浏览或同一个业务动作记了两次 | 事件或页面浏览重复 | 页面上是否有两段脚本；前后端是否共用 insert_id |
| 和另一套统计工具的访客、会话对不上 | 指标与其他工具不一致 | 机器人是否分开计；访客标识是否无 Cookie；日期按哪个时区切 |
| 单页应用只有首页，路由切换没有浏览 | SPA 页面浏览丢失 | 路由是否走 History API；hash 路由有没有打开保留 hash |
| 某一天的数字整段错位，或和导出对不上 | 日期与时区 | 项目时区；客户端时钟与服务器相差是否超过 24 小时 |
| 接口返回 401、403 或 429 | API 401 / 403 / 429 | 密钥是否带上、权限范围是否够、是否打到每分钟或每日上限 |
| 客户端上报失败、积压或换地址 | SDK 网络与重试 | 是网站脚本还是带本地队列的 SDK；HTTP 状态是 429、5xx 还是其它 4xx |
| 网站没有客服气泡 | 客服气泡不显示 | 在线客服开关、w-chat.js 是否加载、域名与移动端隐藏 |
| 助手不回答、数字对不上或一直在澄清 | AI 助手问题 | 规则能否解析；平台模型是否开启；当日调用是否已到上限 |
接入刚做完、还不确定脚本有没有跑起来时，先看 验证安装。仍然要提交问题时，用 联系支持 的模板，不要粘贴完整的 API 密钥。
统计无数据
采集请求可以成功返回，事件仍然不进报表。检查顺序沿着采集端丢弃事件的先后排列。
症状
- 控制台网站统计实时 或对应端的实时页没有新访问。
- 浏览器网络面板里能看到发往
/api/v1/pulse的请求，状态是202。 - 只有部分页面、某种设备，或 App / 小程序没有数据，网站正常。
检查顺序
- 页面上有且只有一段带
data-site的w.js（或对应端已经调用init）。站点标识与控制台「SDK 代码」页一致。 - 地址不是
localhost、127.*、0.0.0.0或[::1]。这些主机名默认不发送；本地调试要加data-allow-local="true"，或显式设置data-api。 - 浏览器没有开启「请勿跟踪」，也没有全局隐私控制。
w.js在这两种信号下默认直接退出，不会发请求。只有脚本上写了data-respect-dnt="false"才继续。 - 网络面板里采集请求的状态码。采集端拒绝也返回
202，响应体为空或只有站点配置，都不能当成「已入库」。 - 请求的来源主机名（以及页面 URL 的主机名）在该项目允许的域名里，含子域名匹配。未登记的应用标识，App / 小程序上报会被静默拒收。
- 项目不是暂停。暂停后采集端记
paused并丢弃。 - 排除规则：路径、主机名、UA 子串、IP、测试设备 ID、内测版本号，命中任意一条即丢弃。
- 免费统计套餐的平台组只有网站。小程序和 App 上报在套餐不含对应平台时记为套餐丢弃，仍然
202。 - 本月事件是否已超过所有者套餐额度。超额后后续事件丢弃，网站本身不受影响，下个自然月（站点时区）重置。
- 你看的日期范围是项目时区的「今天」，见 日期与时区。
原因
采集服务在几乎所有拒绝情况下都返回 202，包括：站点标识不存在、域名不符、暂停、排除规则、套餐不含该平台、月额度用尽、隐私档位整条丢弃、站点每分钟桶打满、异常增速进入采样。采集服务内部异常时也会丢弃并仍返回 202。
隐私判定另有一条容易误判的规则：要求同意但载荷里没有统计同意时，档位降为匿名聚合，页面浏览和自定义事件仍然入库；全埋点在档位低于 2 时整条丢弃，身份操作在档位低于 3 时丢弃（同意 / 退出 / 重新加入的回执除外）。所以「没有点击自动采集」和「没有页面浏览」不是同一种失败。
机器人在默认的「单独统计」里进入机器人报表，不进人类实时流。到 机器人与 AI 爬虫 看，而不是只看人类实时。
修复
- 站点标识、允许的域名、应用标识以控制台登记为准，见 项目与数据源设置。
- 本地调试加上
data-allow-local="true"，或把脚本放到已登记的域名。 - 需要统计开启了「请勿跟踪」的浏览器时，在脚本上设置
data-respect-dnt="false"，并确认合规中心仍按你的政策处理服务端的 DNT / GPC 头，见 CSP、拦截与网络限制 与 隐私与合规中心。 - 暂停的项目恢复；删掉误伤的排除规则。
- 小程序或 App 需要套餐包含对应平台，见 套餐与额度。额度用尽后升级、加油，或等到站点时区的下月 1 日。
- 全埋点没有数据时，先确认项目已开全埋点且套餐允许，再看当前采集档位是不是 1。
验证
用一次无痕窗口打开已登记域名上的页面（不要开「请勿跟踪」）。网络面板出现采集请求后，刷新实时页，应能看到一条人类页面浏览。若只有 202、实时仍为空，在控制台的「异常流量」里看该站当天的拒绝原因（域名、排除、额度、暂停、档位、套餐）。
仍然失败？
按 联系支持 提交，并附上：
项目名称：
页面完整 URL（可打码路径参数）：
脚本是否加载、data-site 前 8 位：
采集请求的状态码与响应体前 200 字：
浏览器是否开启请勿跟踪或全局隐私控制：
看的报表与时间范围（含项目时区）：不要粘贴完整的 API 密钥。站点标识可以写，它是公开的；wck_ 开头的密钥只写前 8 位。
事件或页面浏览重复
先分清是浏览器把同一次浏览送了两次，还是网站和服务器各报了一次。两条链路的去重方式不一样。
症状
- 同一次打开，实时里出现两条相同路径的页面浏览。
- 单页应用每次切换，浏览量加 2。
- 下单、注册在前端和服务端各有一条，漏斗步数翻倍。
检查顺序
- 页面源码里有几段
w.js。后加载的那段发现window.webcount已经就绪会直接退出，不会因为两段标签再记一次。若你看到两次请求，第二段多半不是同一份脚本，而是另一段统计代码或框架插件又调了pageview()。 - 自动记录与手动
pageview()是否打在同一个 URL 上。URL 与上一次相同（含自动记录刚写过的那次）会被脚本忽略。 - 采集端短窗口：同一访客、同一类型、同一事件名、同一路径、同一查询串、同一属性签名，页面浏览 2 秒内只留一条，其它事件 1 秒内只留一条。离开和 Web Vitals 按会话加事件名加路径，窗口 5 秒。窗口之外的第二次真实浏览会留下。
- 服务端
POST /api/v1/track是否带了insert_id。带了之后，同批重复以及事件时间前后 1 天内已入库的同一insert_id会被丢掉，先到的那条生效。没带时，前后端各报一次就是两条。 track_update/track_overwrite用insert_id去改已有事件，不是再插一条。缺insert_id时这条更新不会按你的预期合并。
原因
网站脚本没有跨请求的持久去重键。它靠「同一 URL 不连续记两次」和采集端几秒的指纹挡住双击、重复标签和重放。业务事实如果浏览器和服务端都报，只有 insert_id 能把它们收成一条。
replaceState 只改了 state、没改 URL，脚本不会多记。查询串变化会算成另一条页面浏览，采集端去重指纹里包含查询串。
修复
- 页面只保留一段 TapCub 脚本。框架接入不要再手写一次
pageview()，除非你用data-auto-track="false"关掉了自动记录，见 页面浏览与 SPA。 - 订单、支付、注册这类以服务端为准的事件，只在服务端上报，并带稳定的
insert_id（例如订单号，最长 36 字符）。前端若也要记行为，用另一个事件名，不要和purchase同名同键。见 服务端事件与日志导入。 - 重试同一批服务端事件时沿用原来的
insert_id，不要每次生成新的。
验证
无痕窗口打开页面一次，实时里该路径只有一条页面浏览。再刷新，应新增一条（超过 2 秒）。用同一 insert_id 把服务端事件发两次，响应里第二次应被拒绝或不再增加事件条数；debug=1 只校验、不入库，适合先看警告。
仍然失败？
按 联系支持 提交，并附上两条重复事件的时间、路径或事件名、是否同时有浏览器请求和服务端请求。服务端示例里删掉密钥，insert_id 可以原样保留。不要粘贴完整的 API 密钥，需要指明哪一把时只写前 8 位。
SPA 页面浏览丢失
网站脚本只会在它监听得到的导航上记页面浏览。
症状
- 第一次打开有一条页面浏览，之后的前端路由没有。
- hash 路由（
/#/pricing）的每一节都算成首页。 - 关掉自动采集之后，连首页也没有了。
检查顺序
- 路由是否调用
history.pushState或history.replaceState。脚本包装了这两个方法，并监听popstate。Vue Router、React Router、Next.js、Nuxt 的 history 模式走这条路径，不需要再手写pageview()。 - 地址是不是 hash 路由。默认会丢掉
#及其后面的部分，/docs#intro与/docs#faq是同一页，也不会听hashchange。hash 路由要在脚本上加data-hash="true"。 - 新 URL 是否和上一次完全相同。相同则忽略，所以只改 state、不改 URL 的
replaceState不会多记，也不会把「没变的 URL」记成新页面。 data-exclude是否罩住了这些路径。排除只看location.pathname，不含查询串和 hash。data-auto-track是不是"false"。设成 false 后，首次浏览、路由跟随、停留时长一起关掉，只剩你自己调用的pageview()和track()。- 标题晚于下一个事件循环才更新时，URL 仍然是新的，标题可能还是上一页。这不是「没记上」，只是标题旧了。
原因
脚本不读取框架内部的路由状态。它只看 History API、后退前进，以及你显式打开的 hash 监听。不走这些 API 的路由（自定义事件换视图、且不改地址）不会自动产生页面浏览。
采集端还会把查询串从统计用的页面路径上拿掉。路由若只改 ?tab=，脚本会发请求（查询串变了，和上次 URL 不同），页面报表里仍可能落在同一条路径上。
修复
hash 路由：
<script async src="https://app.tapcub.com/w.js" data-site="{{SITE_KEY}}" data-hash="true"></script>路由不改地址时，在路由完成的回调里调用 window.webcount.pageview()。若自动记录也开着，而此时 URL 已经变了，不要再呼一次，否则同一 URL 会被忽略或在 2 秒去重窗外再记一条。各框架写法见 Vue 接入指南、React 接入指南、Next.js 接入指南、Nuxt 接入指南，规则全文见 页面浏览与 SPA。
验证
打开网站，在网络面板过滤 collect。首次加载应有一条。再点到另一个路径，下一个事件循环应再有一条，请求体里的页面 URL 是新路径。实时页出现这两条，路径不同。
仍然失败？
按 联系支持 提交：框架与路由模式（history 或 hash）、脚本标签上的 data-hash / data-auto-track / data-exclude、两次点击之间网络面板有没有新的采集请求。不要粘贴完整的 API 密钥。
指标与其他工具不一致
先让两边用同一天、同一种人，再比数字。TapCub 的默认算法和依赖 Cookie 的工具不是同一套计数。
症状
- 访客数明显低于另一套工具，或每天「新访客」偏多。
- 会话数更多或更少。
- 某个页面的浏览量少一截，带查询串的 URL 被合成了一页。
- 把机器人算进去之后，总数才接近。
检查顺序
- 日期范围是否按项目时区的自然日，而不是浏览器本地时区或 UTC 零点。见 日期与时区。
- 对比的是人类流量还是含机器人。默认机器人模式是「单独统计」：人类报表不含搜索引擎机器人和 AI 爬虫，那些在 机器人与 AI 爬虫。模式为「丢弃」时机器人不入库。模式为「关闭」时机器人和人类混在一起。
- 访客怎么识别。
w.js不写 Cookie、不写本地存储。访客标识由服务端用 IP 与 UA 做 HMAC。换网络、换浏览器、严格档每天轮换盐，都会变成另一个访客。依赖第一方 Cookie 的工具会把同一个人计得更「稳」。口径见 访客、用户与身份归一 与 统计口径。 - 会话规则默认空闲 30 分钟、最长 24 小时，午夜切分默认关。另一套工具若用 30 分钟以外的超时，会话数不会相同。见 会话。
- 页面路径：采集端统计页面时去掉查询串和末尾的
/，路径最长 512 字符。URL 含#/时才把 hash 并进路径。另一套工具若把每个查询串当成不同页面，页面表会对不上，浏览量总和仍应接近。 - 开启「请勿跟踪」或全局隐私控制的浏览器，
w.js默认不运行，这些人不会出现在 TapCub 里，另一套工具仍可能计到。 - 异常增速：某一分钟超过 1000 条且高于过去 7 天同时段均值的 10 倍时，采集端会进入约 10 分钟的采样（每 10 条收 1 条）。这只在尖峰时发生，平时不会抽样。
原因
差异通常来自三件独立的事：谁被算进「人」、同一个人怎么被认成同一个人、一天从几点切到几点。TapCub 把机器人拆开、用无 Cookie 的访客标识、按项目时区切日。把这三项对齐之后，浏览量仍可能差在路径归一和短窗口去重（页面浏览 2 秒内同指纹只留一条）。
修复
- 对比时只取人类、同一项目时区的同一自然日，并在两边都排除内部 IP。
- 要看「同一个人跨天」的稳定程度，需要识别模式（采集档位 3）和登录标识，而不是和 Cookie 工具比匿名访客。见 接入前的隐私选择。
- 会话超时要改时，在项目的会话规则里改，改完再比，不要用默认 30 分钟去对另一套 15 分钟的定义。
- 营销参数要留在页面报表里时，看 项目与数据源设置 的 URL 参数处理；默认统计页会去掉查询串。
验证
选一个低流量、你能自己复现的小时。无痕窗口访问 3 个固定 URL，每个停留超过 2 秒。人类实时应增加 3 条浏览、1 个访客。换一个无「请勿跟踪」的浏览器再对一次另一套工具的同一小时。
仍然失败？
按 联系支持 提交两边的指标名、时间范围、时区，以及 TapCub 里是人类还是含机器人。不要粘贴完整的 API 密钥；导出样例里的邮箱、手机号和 IP 删掉后再发。
日期与时区
TapCub 的一天按项目时区切，不按你电脑的时区，也不按 UTC 的零点，除非项目时区就是 UTC。
症状
- 晚上的访问出现在「明天」或「昨天」。
- 和另一套按 UTC 或按浏览器时区出数的工具差一天的边界。
- 服务端补报的历史事件落在收到当天，而不是事件真正发生的那天。
检查顺序
- 打开 控制台配置设置常规，看「时区」。新建项目时填的就是这个值。日报、周报、月报、会话跨午夜（若打开）和按小时的热力都用它。
- 对比的另一套工具用的时区是否相同。相同自然日再比人数，见 指标与其他工具不一致。
- 浏览器采集的时间校正：采集端用「收到时刻 −（发送时刻 − 客户端时刻）」还原事件时间。还原结果与收到时刻相差超过 24 小时时，改用服务器收到的时间。手机日期设错、或离线很久才发出的事件，会落在收到那天。
- 服务端
POST /api/v1/track的time是毫秒时间戳。与服务器相差超过 72 小时会被换成接收时间。补历史数据时不要一次塞进超出这个窗口的时间。 - 月额度按站点时区的自然月计数，不是按 UTC 月。靠近月初、月末看「超额」时，用项目时区判断是不是新的一月。
原因
事件可以带着客户端时钟入库，但分日、分月的报表边界是项目时区。两套边界叠在一起：时钟误差在 24 小时（浏览器）或 72 小时（Track 接口）以内会尽量保留客户端时间；超出则整条改记为接收时间，于是历史补报会堆在补报当天。
修复
- 把项目时区改成业务所在地的 IANA 时区（例如
Asia/Shanghai）。已经按旧时区切好的历史日不会自动重排，改完之后的新事件按新边界进报表。 - 补历史时，
time放在服务器当前时间的 72 小时以内，或接受它们记在接收日。需要更早的日志时走日志导入，见 服务端事件与日志导入，不要依赖超出窗口的time。 - 导出后在表格里按项目时区解释日期，不要再把时间戳当成 UTC 零点切一天。接口里的日期约定见 通用约定。
验证
记下项目时区。在该时区的 23:50 之后打开一次页面，实时的「今天」应仍是这一天，而不是 UTC 的下一天（项目不是 UTC 时）。把电脑时钟拨快超过 24 小时再访问一次，这条应落在服务器收到的时刻，而不是拨快后的那个日期。
仍然失败？
按 联系支持 提交项目时区、你期望的日期、报表上看到的日期，以及事件是浏览器采集还是 Track 接口。不要粘贴完整的 API 密钥。