如何在React+TypeScript(.tsx)项目中集成Countly SDK Web

countly-sdk-web 官方默认没有提供ES模块规范的具名导出，也没有内置TypeScript类型声明，要实现import { Countly } from 'countly-sdk-web'的导入写法、在页面加载时完成初始化，按以下步骤配置即可，所有.tsx文件均可正常调用SDK能力。

1. 安装SDK依赖 #

在项目根目录执行对应包管理工具的安装命令：

npm install countly-sdk-web
# 用yarn就执行 yarn add countly-sdk-web
# 用pnpm就执行 pnpm add countly-sdk-web

2. 补充TypeScript类型声明 #

官方包未携带TS类型定义，直接导入会报类型错误。在项目src目录下新建countly-sdk-web.d.ts文件，写入以下模块声明即可解决TS校验问题：

declare module 'countly-sdk-web' {
  interface CountlyInitConfig {
    app_key: string;
    url: string;
    debug?: boolean;
    offline_mode?: boolean;
    track_sessions?: boolean;
    [key: string]: any;
  }

  interface CountlyInstance {
    init(config: CountlyInitConfig): void;
    track_pageview?: (path: string) => void;
    add_event?: (event: { key: string; count?: number; segmentation?: Record<string, any> }) => void;
    [key: string]: any;
  }

  export const Countly: CountlyInstance;
}

确认tsconfig.json的include配置覆盖了src目录下的.d.ts文件，默认创建的React+TS项目都会自动覆盖，无需额外修改。如果后续用到更多SDK方法，直接在CountlyInstance接口里补充对应类型即可。

3. 全局初始化SDK #

不要在业务组件里重复初始化，直接在项目入口文件（通常是src/main.tsx或src/index.tsx，即React根节点挂载的文件）中，在React应用挂载前完成Countly初始化，保证页面加载时第一时间完成SDK启动：

import React from 'react';
import ReactDOM from 'react-dom/client';
import { Countly } from 'countly-sdk-web';
import App from './App';

// 页面加载即初始化Countly
Countly.init({
  app_key: '替换为你在Countly平台创建应用对应的App Key',
  url: '替换为你的Countly服务访问地址',
  debug: import.meta.env.DEV, // 开发环境开启调试日志，生产环境自动关闭
  track_sessions: true,
  // 其余配置参数和官方JavaScript版文档的参数完全一致，按需追加即可
});

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

4. 业务代码中调用SDK #

初始化完成后，在任意.tsx文件中都可以直接导入Countly实例调用API，调用方式和官方JS示例完全一致，举个常见的页面浏览上报例子：

import { useEffect } from 'react';
import { Countly } from 'countly-sdk-web';

export default function Home() {
  useEffect(() => {
    // 上报页面访问
    Countly.track_pageview?.('/home');
    // 上报自定义事件
    Countly.add_event?.({
      key: 'home_page_view',
      count: 1,
      segmentation: { source: 'direct' }
    });
  }, []);

  return <div>首页内容</div>;
}

常见注意事项 #

• Countly.init全局只调用1次即可，重复初始化会导致事件重复上报、会话统计异常
• 如果导入后Countly值为undefined，请升级countly-sdk-web到22.0.0以上版本，低版本不支持ES模块具名导出
• 方法调用时建议加可选链?.，避免极端初始化时序问题导致的前端报错

内容的提问来源于stack exchange，提问作者Akhmad Zaki