# EarthSDK3 Assets

EarthSDK3 资源管理插件，支持自动检测并适配 Vite、Webpack、Rspack 等主流构建工具。

## 安装

```bash
npm install earthsdk3-assets
```

## 特性

- 🔍 **自动检测构建工具** - 根据项目依赖自动选择对应插件
- ⚡ **支持 Vite** - 原生 ESM，极速开发体验
- 📦 **支持 Webpack** - 兼容 Webpack 5.x
- 🚀 **支持 Rspack** - 字节跳动出品，Webpack API 兼容
- 💾 **增量下载** - 智能缓存，只下载变更资源
- 🎯 **零配置** - 开箱即用，自动注入脚本
- 📁 **不污染项目** - 开发模式不创建物理文件
- 🌐 **内网环境支持** - 网络不可用时自动使用本地缓存
- ⚙️ **灵活配置** - 支持自定义资源路径
- 📂 **自定义资产** - 通过 `customAssets/` 目录附带本地资源，构建时自动拷贝到输出目录

## 使用方法

### 自动检测（推荐）

插件会自动检测你项目使用的构建工具：

#### Vite 项目

```typescript
// vite.config.ts
import earthsdkAssets from 'earthsdk3-assets';

export default {
    plugins: [
        earthsdkAssets()
    ]
};
```

#### Webpack 项目

```javascript
// webpack.config.js
const earthsdkAssets = require('earthsdk3-assets');

module.exports = {
    plugins: [
        earthsdkAssets()
    ]
};
```

#### Rspack 项目

```javascript
// rspack.config.js
const earthsdkAssets = require('earthsdk3-assets');

module.exports = {
    plugins: [
        earthsdkAssets()
    ]
};
```

### 手动指定构建工具

如果自动检测失败，可以强制指定：

```typescript
// Vite
import earthsdkAssets from 'earthsdk3-assets';
export default {
    plugins: [earthsdkAssets({ forceTool: 'vite' })]
};

// Webpack
const earthsdkAssets = require('earthsdk3-assets');
module.exports = {
    plugins: [earthsdkAssets({ forceTool: 'webpack' })]
};

// Rspack
const earthsdkAssets = require('earthsdk3-assets');
module.exports = {
    plugins: [earthsdkAssets({ forceTool: 'rspack' })]
};
```

### 自定义配置

```typescript
// Vite 示例
import earthsdkAssets from 'earthsdk3-assets';

export default {
    plugins: [
        earthsdkAssets({
            forceTool: 'vite',
            assetsPath: 'custom/assets',           // 资源文件拷贝路径，默认为 'earthsdk3-assets'
            scriptSrc: './custom/assets/earthsdk3-assets.js'  // script 标签路径
        })
    ]
};
```

### 子路径导入

也可以直接导入特定构建工具的插件：

```typescript
// Vite
import earthsdkAssets from 'earthsdk3-assets/vite';

// Webpack
const earthsdkAssets = require('earthsdk3-assets/webpack');

// Rspack
const earthsdkAssets = require('earthsdk3-assets/rspack');
```

### 自定义资产目录 (customAssets)

`customAssets/` 是位于包根目录的本地自定义资产目录，用于存放**不参与远程下载、由用户自行维护**的资源（例如项目专属的图片、模型、配置等）。

- **开发模式**：通过虚拟路径直接访问，URL 为 `/earthsdk3-assets/customAssets/...`（Vite 中间件按需返回；Webpack/Rspack 将目录加入编译产物）。
- **生产模式**：构建时将整个 `customAssets/` 目录递归拷贝到 `dist/earthsdk3-assets/customAssets/`，且**不依赖远程清单**——即使资源清单缺失或内网无法下载，自定义资产仍会正常拷贝。
- **发布**：`customAssets/` 已包含在 `package.json` 的 `files` 字段中，会随包发布到 npm。

目录内容可任意组织（支持多级子目录），例如：

```
earthsdk3-assets/
└── customAssets/
    ├── logo.png
    └── models/
        └── demo.glb
```

访问时对应路径为 `/earthsdk3-assets/customAssets/logo.png`、`/earthsdk3-assets/customAssets/models/demo.glb`，开发与生产环境路径一致。

## 配置选项

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `forceTool` | `'vite' \| 'webpack' \| 'rspack' \| 'vue-cli'` | 自动检测 | 强制指定构建工具 |
| `assetsPath` | `string` | `'earthsdk3-assets'` | 资源文件拷贝到输出目录的路径 |
| `scriptSrc` | `string` | `'./earthsdk3-assets/earthsdk3-assets.js'` | 注入到 HTML 的 script 标签 src 属性 |

## 工作原理

### 开发模式

1. **资源下载** - 从远程服务器下载 EarthSDK3 所需的静态资源到 `node_modules/earthsdk3-assets/`
2. **智能缓存** - 使用 MD5 校验，只下载变更的文件
3. **虚拟路径服务** - 开发服务器提供 `/earthsdk3-assets/*` 路径的资源服务，不创建物理文件
4. **HTML 注入** - 自动在 HTML 中注入 `<script src="./earthsdk3-assets/earthsdk3-assets.js">`

### 生产模式

1. **资源拷贝** - 构建时根据资源清单将资源拷贝到 `dist/earthsdk3-assets/` 目录
2. **自定义资产附带拷贝** - 将本地 `customAssets/` 目录递归拷贝到 `dist/earthsdk3-assets/customAssets/`（不依赖远程清单，离线/内网环境同样生效）
3. **HTML 注入** - 自动在 HTML 中注入脚本引用

### 内网环境支持

当项目从外网拷贝到内网环境后，如果无法访问远程资源服务器：

1. 插件会检测本地缓存文件是否存在
2. 如果缓存存在，使用本地缓存继续运行
3. 如果缓存不存在，抛出异常

## 目录结构

```
earthsdk3-assets/
├── src/
│   ├── core/
│   │   ├── downloadAssets.js     # ESM 版本资源下载核心逻辑
│   │   ├── downloadAssets.cjs    # CommonJS 版本
│   │   ├── copyAssets.js         # ESM 版本文件拷贝工具
│   │   └── copyAssets.cjs        # CommonJS 版本
│   ├── plugins/
│   │   ├── vite.js               # Vite 插件 (ESM)
│   │   ├── webpack.cjs           # Webpack 插件 (CommonJS)
│   │   └── rspack.cjs            # Rspack 插件 (CommonJS)
│   ├── index.js                  # ESM 入口（自动检测）
│   ├── index.cjs                 # CommonJS 入口
│   └── index.d.ts                # TypeScript 类型声明
├── glb/                          # 下载的 GLB 模型资源
├── img/                          # 下载的图片资源
├── customAssets/                 # 本地自定义资产目录（不参与远程下载，构建时附带拷贝到输出目录）
├── earthsdk3-assets.js           # 资源加载器脚本（远程下载）
├── .assets-version               # 版本缓存文件
├── .assets-manifest.json         # 资源清单缓存
└── package.json
```

## 构建工具检测优先级

插件按以下顺序检测构建工具：

1. **Vite** - 检查 `vite` 依赖或 `vite.config.*` 文件
2. **Rspack** - 检查 `@rspack/core` 依赖或 `rspack.config.*` 文件
3. **Vue CLI** - 检查 `@vue/cli-service` 依赖（基于 Webpack 5）
4. **Webpack** - 检查 `webpack` 依赖或 `webpack.config.*` 文件

## 注意事项

- **Webpack/Rspack 项目**需要安装 `html-webpack-plugin` 或 `@rspack/plugin-html` 以支持 HTML 脚本注入
- **Vue CLI 项目**内置 `html-webpack-plugin`，无需额外安装
- **所有构建工具插件均为可选依赖**，未使用的构建工具不会引起报错
- **开发模式**下资源通过虚拟路径访问，不创建物理文件到项目目录
- **生产模式**下资源会根据清单文件拷贝到构建输出目录，`customAssets/` 目录也会附带拷贝（不依赖清单）
- **内网环境**下如果已有缓存，即使无法访问外网也能正常运行

## 许可证

ISC