PostHog JS Bundle瘦身终极指南:6个动态加载与Tree-shaking性能优化技巧
PostHog JS Bundle瘦身终极指南:6个动态加载与Tree-shaking性能优化技巧
PostHog JS(posthog-js)是 PostHog 官方提供的浏览器端埋点 SDK,负责把你的网页或 Web 应用的使用数据发送到 PostHog,并支持 autocapture(自动采集点击等交互)。但埋点 SDK 动辄几百 KB,直接全量引入会拖慢首屏加载。本文将带你掌握 posthog-js 的 Bundle 瘦身实战技巧:利用官方提供的动态加载机制和 Tree-shaking 优化,在不牺牲功能的前提下把包体积压到最小,让你的站点更快一步。🚀
为什么你的 Bundle 里塞了一堆不需要的代码?
posthog-js 的功能远不止「发一个事件」:会话回放(session replay)、功能开关(feature flags)、自动采集(autocapture)、日志(logs)、调研问卷(surveys)、web-vitals 性能指标……如果这些模块全部静态打进初始 Bundle,用户只为记一次点击却要先下载几 MB 的 JS。
好消息是,posthog-js 仓库本身就是「按需加载」的教科书级实践。下图来自内置 rrweb 会话回放的测试快照,展示了 SDK 录制/回放能力的实际效果——而这类重功能在新版架构里恰恰是被动态加载的:
两条官方瘦身路径,按需选择
经典构建:挑选正确的入口文件
posthog-js 经典版(packages/browser/)通过 src/entrypoints/ 目录发布了大量细分入口,构建配置见 rollup.config.mjs。你可以只引入真正需要的模块,而不是「全家桶」:
- 只需要核心埋点:用
module.slim(module.slim.es.ts) - 需要会话回放但想控制第三方依赖:对比
array.full与no-external变体(array.full.no-external.ts) - 单独使用某个功能:如 recorder.ts(会话录制)、surveys.ts、web-vitals.ts、dead-clicks-autocapture.ts、extension-bundles.es.ts 等扩展打包入口
仓库还内置了 Bundle 对比工具 compare-array-bundle-size.mjs,方便你量化不同入口的体积差异。📏
下一代 @posthog/browser:内置动态加载
packages/browser-next/(包名 @posthog/browser)采用扩展(Extension)架构,是动态加载的最佳实践样本:
- 核心先行:初始化时只加载「有界缓冲」的核心;第一条被接纳的事件才会通过动态 import 加载队列调度和 Capture V1 上报模块(automatic-analytics.ts 中的字面量动态导入)
- 功能按需:feature flags、logs、surveys 编排、autocapture 默认在异步初始化阶段动态加载(index.ts),不需要则用
flags: false、surveys: false、autocapture: false直接剔除 - 上报时机可控:默认
load: 'lazy',首屏不下载上报模块;追求即时性可配analytics: { load: 'eager' } - 细粒度子路径导出:
@posthog/browser/core、/flags、/analytics、/logs、/surveys、/autocapture(见 package.json),配合 lazy.ts 这类 fixture 可以精确测量「初始 chunk」大小
💡 经典
<script>安装方式同样支持瘦身:在 CDN 脚本 URL 上用查询参数(如flags=false、autocapture=false)关闭不需要的默认功能,解析逻辑见 snippet/runtime.ts。
6 个 Tree-shaking 实战技巧
以下规则均源自官方架构文档 ARCHITECTURE.md,你在自己项目中引入 posthog-js 时同样适用:
- 确认
sideEffects: false已生效。@posthog/browser声明了sideEffects: false(package.json),打包器可以放心删除未使用的导出。检查你依赖链上各包的 sideEffects 声明,别让它被错误标记拖住摇树效果。 - 类型导入一律用
import type。类型导入不会变成 JS 运行时导入,不会把模块拉进 Bundle(架构文档第 4.1 节)。 - 精确子路径导入,别碰根 barrel。需要哪个功能就导入哪个子路径(如
@posthog/browser/flags),避免引入根入口的整张依赖图。 - 保持 barrel 窄化,禁止跨产品边界
export *。通配导出会让打包器无法确定哪些代码可删。 - 不要用运行时开关冒充瘦身边界。
if (options.enableX)里的代码早已被静态导入,开关只影响行为、不减体积;真正省体积要靠导入边界(独立子路径 + 动态 import)。 - 保持导入图无环、模块零副作用。循环依赖会破坏 tree shaking 并改变初始化顺序;模块求值阶段禁止读 storage/DOM、挂监听、发请求,一切副作用工作推迟到工厂函数或方法调用中执行。
测量与验证:别猜,直接量
瘦身必须用数据说话,仓库提供了现成手段:
- check-bundle-size.mjs:用 esbuild 按「静态闭包 / 懒加载」分别构建,输出 minified、gzip、brotli 三种体积和逐模块字节归因,并断言禁止模块(如 flags、logs、autocapture)不得出现在初始 chunk 中
- rollup.config.mjs 内置
rollup-plugin-visualizer,生成bundle-stats-*.html可视化报告,一眼看出「谁在占体积」 - 用
sideEffects: false+ metafile 输入归因,验证每个未用模块确实被打包器剔除
瘦身速查清单
| 技巧 | 关键动作 | 适用场景 |
|---|---|---|
| 选对入口 | 用 slim / no-external / 功能子入口替代 full 构建 | 经典 posthog-js |
| 动态加载 | 依赖 load: 'lazy' 默认值或显式动态 import |
@posthog/browser |
| 功能关闭 | flags: false、surveys: false 等 |
两者均适用 |
| 类型导入 | import type 替代运行时导入 |
所有项目 |
| 子路径导入 | 只导入实际用到的扩展入口 | 所有项目 |
| 体积度量 | 运行 bundle-size 脚本并核对初始 chunk | CI 守门 |
写在最后
posthog-js 的 Bundle 瘦身不是「压缩得更狠」,而是架构上先划好边界:核心保持最小,可选功能全部置于导入边界之后,再由 Tree-shaking 和动态加载把体积交给真正需要的用户。把上面的清单落到你的构建流水线里,首屏性能提升立竿见影。
延伸阅读:
- 架构与 Tree-shaking 完整规则:ARCHITECTURE.md
- 新客户端使用文档:README.md
- 经典入口一览:src/entrypoints/
