安装与导入

安装

@tripo3d/lens 发布在 GitHub Packages（私有 registry）。请先完成 GitHub Packages 认证配置，然后：

pnpm

pnpm add @tripo3d/lens

npm

npm install @tripo3d/lens

yarn

yarn add @tripo3d/lens

运行时依赖 @tripo3d/fingerprint（稳定 device id）与 web-vitals（性能指标）：二者都声明为 dependencies，安装 lens 时由包管理器自动一并装上，无需手动添加。其中 fingerprint 在 ESM 产物里保持 external。

面向用户的五个入口

lens 对外暴露五个入口，绝大多数业务只用主入口 .：

入口	平台	用途
@tripo3d/lens	浏览器	主入口。TripoLens 采集内核、各插件、类型，99% 的接入只用它。
@tripo3d/lens/server	仅 Node	SSR Part B 服务端采集原语，仅在手动 SSR 接线时直接 import。依赖 node:async_hooks / node:crypto，禁止在浏览器侧 import。
@tripo3d/lens/react	浏览器	React 适配层：useTraceProps / <Trace> / <TraceProvider> 等，见 React 接入。
@tripo3d/lens/vue	浏览器	Vue 适配层：TripoLensVue 插件（v-trace 指令）与 useTrace() 等，见 Vue 接入。
@tripo3d/lens/nuxt	Nuxt	Nuxt 适配器（Nuxt Module）：客户端接线 + 服务端 SSR 采集打包，见 Nuxt 接入。

框架适配子路径按需依赖对应框架（vue ^3.3 / react ^17 || ^18 || ^19 / nuxt ^4 等，均为 optional peerDependencies）——只用主入口时无需安装任何框架。

包内另有两个内部子路径，业务无需也不应直接 import，故不计入上表：@tripo3d/lens/debug（devtools 调试桥，内核在 debug 开启时动态加载）；@tripo3d/lens/shared（/server 与主入口共用 wire 类型 + 同构纯函数的单一事实源，仅由插件内部静态引用）。

/server 仅服务 SSR Part B

/server 是给「服务端先采集、客户端统一上报」的 SSR 场景用的底层原语。普通 Vue/React/Nuxt 接入不需要直接 import 它——Nuxt 的服务端接线请用框架适配器 @tripo3d/lens/nuxt。

ESM 导入（打包器 / 框架项目）

lens 仅发布 ESM 产物（无 UMD / <script> 版本），请在支持 ESM 的打包器或框架工程（Vite / Nuxt / webpack 等）中使用。

import {
  TripoLens,
  // 按需 opt-in 插件
  TrackingPlugin,
  ErrorPlugin,
  PerformancePlugin,
} from '@tripo3d/lens';

主入口对外导出的核心成员：

导出	说明
TripoLens / TripoLensParams	主类与构造参数类型
AttributionPlugin / IdentityPlugin	默认插件（一般无需手动 new，构造时已自动装）
TrackingPlugin / ErrorPlugin / PerformancePlugin	opt-in 插件及其 *Options 类型
RemoteTraceConfig、各 *Payload 等	远程配置与事件 payload 类型

完整导出清单见 API Reference（typedoc 自动生成）。

SSR import 安全（≠ 支持 SSR 采集）

即便在服务端环境 import 主入口也不会爆错——所有浏览器副作用（读 window / localStorage / 计算指纹 / 发请求）都只在浏览器侧执行，SSR 阶段 init() 与上报均为 no-op。但「不爆错」不等于「采集 SSR 数据」：主入口在服务端是全程 no-op。原理见 架构总览 · SSR 安全。

下一步

• 初始化 —— new + await init() 的完整流程与时序
• 构造参数 —— TripoLensParams 全字段