Google Analytics 4 的 gtag.js 脚本必须放在 <head> 中，否则会导致首次页面加载的 page_view 事件丢失；应置于 <head> 顶部，确保尽早执行以捕获用户快速滚动或点击行为，避免因延迟加载或置于 <body> 底部造成数据漏报。
Google Analytics 4 的 gtag.js 脚本必须放在 <head> 里
不放 <head>，会导致首次页面加载事件丢失，尤其是用户快速滚动或点击时。GA4 依赖脚本尽早执行来捕获 page_view，延迟加载或塞在 <body> 底部会让部分访问无法上报。
- 复制 GA4 测量 ID（形如
G-XXXXXXXXXX），不是旧版 UA- 开头的 ID - 在
<head>内顶部位置插入官方gtag.js脚本（不是 analytics.js） - 确保没有其他同域名下的 GA4 脚本重复加载，否则会触发多次
page_view
手动触发 gtag('config', 'G-XXXXXXXXXX') 前要检查 domain 设置
默认配置下，gtag('config', ...) 会自动发送 page_view，但如果网站用了子域名（如 blog.example.com）、本地开发（localhost）或 HTTP 协议，GA4 可能因 cookie 限制漏数据。
- 本地测试时，必须加
{ 'cookie_domain': 'none' }参数，否则localhost下不存 cookie，事件不上报 - 多子域共用一个 GA4 媒体资源时，需显式设
{ 'cookie_domain': 'example.com' } - HTTP 站点无法使用 Secure Cookie，GA4 控制台会提示 “No data received”，建议至少用 HTTPS 或本地
127.0.0.1
gtag() 发送自定义事件时，参数名不能含空格或特殊字符
GA4 后台只接受小写字母、下划线和数字组成的事件名与参数键，比如 'click_button' 合法，'Click Button' 或 'click-button' 会被静默丢弃，且控制台不报错。
- 事件名推荐用蛇形命名（
user_registration_success），避免驼峰或中划线 - 参数值尽量用字符串或数字，不要传
undefined或函数——gtag('event', 'download', { 'file_type': undefined })会导致整条事件被过滤 - 调试时打开浏览器开发者工具 → Network 标签页，筛选
collect?请求，确认 payload 中en（event name）和ep.（event params）字段存在且格式合规
验证 GA4 是否真正生效，别只看实时报告
GA4 实时报告有 1–3 分钟延迟，且默认过滤掉内部 IP（比如你自己的办公网络），容易误判“没数据”。真正可靠的验证方式是三步交叉比对。
立即学习“前端免费学习笔记（深入）”；
- 第一步：在 GA4 管理后台开启“调试视图”（DebugView），同时在 Chrome 打开网页并启用
gtag('set', 'debug_mode', true) - 第二步：用浏览器扩展（如 “Google Analytics Debugger”）检查控制台是否输出
[G] event: page_view类日志 - 第三步：等 24 小时后查“标准报告” → “实时” → “流量获取”，看是否有非零的“活跃用户”和“页面浏览”——这才是最终生效信号
GA4 的事件模型和旧版完全不同，一次页面加载不再自动附带用户属性，所有维度（比如登录状态、会员等级）都得靠 gtag('config', ..., { 'user_properties': {...} }) 显式传入，这点很容易被忽略。
