打包产物与框架接入说明

本文说明 TRRO Web SDK 的打包产物构成，以及在不同前端框架中引用时的注意事项。

打包产物目录结构

SDK 构建后会在 dist/trro-sdk/<version>/ 目录下产出如下结构：

dist/trro-sdk/<version>/
├── index.js                          # UMD 产物，已包含运行所需的全部依赖，开箱即用
├── index.esm.js                      # ESM 产物，原生 ES Module，供现代打包工具按需 tree-shaking
├── index.d.ts                        # TypeScript 类型声明（中文）
├── index_en.d.ts                     # TypeScript 类型声明（英文）
├── index.js.LICENSE.txt              # UMD 产物的第三方依赖许可证说明
├── index.esm.js.LICENSE.txt          # ESM 产物的第三方依赖许可证说明
├── demo_public_cloud.html            # 公有云接入 Demo
├── demo_public_cloud_intl.html       # 公有云国际站接入 Demo（中文）
├── demo_public_cloud_intl_en.html    # 公有云国际站接入 Demo（英文）
├── demo_private_cloud.html           # 私有云接入 Demo
├── demo_js/                          # Demo 所用脚本
│   ├── demo.js                       # Demo 主逻辑
│   ├── i18n.js                       # Demo 国际化文案
│   ├── jquery-3.7.1.min.js           # Demo 依赖：jquery
│   └── tailwindcss.js                # Demo 依赖：tailwindcss
├── docs/                             # SDK 文档（中文），由 JSDoc 生成
└── docs_en/                          # SDK 文档（英文），由 JSDoc 生成

其中 index.js 与 index.esm.js 为两种模块格式的核心产物：

index.js 为 UMD 产物，已包含运行所需的全部依赖，开箱即用。

在 React / Vue 等框架中引用

现代前端框架（React、Vue 等）通常基于 Webpack、Vite 等打包工具构建，会默认对 node_modules 中的依赖进行二次编译（transpile）。

index.js（UMD 产物）是经过混淆、已打包的成品，若被框架的 Babel / SWC 再次编译，可能引入不可预期的副作用（如混淆代码被二次转换后行为异常、体积膨胀等）。

推荐以下两种方式之一：

方式一：配置 Babel 忽略 SDK（仍使用 UMD 产物）

确保打包工具不要对 SDK 进行二次编译。若使用 Webpack 的 babel-loader，可在 rule 上通过 exclude 排除：

// webpack.config.js
module: {
  rules: [
    {
      test: /\.js$/,
      exclude: /node_modules[\\/]trro_web_sdk/,
      use: 'babel-loader',
    },
  ],
}

若使用 Babel 配置文件，可通过 ignore / exclude 跳过 SDK：

// babel.config.json
{
  "presets": ["@babel/preset-env"],
  "ignore": ["node_modules/trro_web_sdk"]
}

只要打包工具跳过对 SDK 文件的 transpile，UMD 产物即可安全使用。

方式二：直接使用 ESM 产物

若你的构建链路支持原生 ESM（Vite、Rollup 或 Webpack 5 outputModule），可直接引用 index.esm.js：

import { TRROSDK } from 'trro_web_sdk/dist/trro-sdk/<version>/index.esm.js';

ESM 产物同样已打包依赖，且能被打包工具正确识别为模块、参与 tree-shaking，无需额外配置 Babel 忽略。