On this page

## 打包产物与框架接入说明

本文说明 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 | 通用模块格式，可被 `<script>` 标签、`CommonJS`、`AMD` 等方式加载
`index.esm.js` | ESM | 原生 ES Module，供现代打包工具（如 Vite、Rollup、Webpack 5）按需 tree-shaking 引入

`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 忽略。

Type anything to view search result