earthsdk3-assets 3.0.14 → 3.0.15

package/README.md

@@ -1,16 +1,146 @@
-# 一、设置资源入口
-
-```html
-<!-- index.html -->
-<script src="js/earthsdk3-assets/earthsdk3-assets.js"></script>
-
-```
-
-# 二、使用资源
-
-```js
-
-const strUrl = '${earthsdk3-assets-script-dir}/assets/img/add.png';
-
-```
-
+# EarthSDK3 Assets
+
+EarthSDK3 资源管理插件，支持自动检测并适配 Vite、Webpack、Rspack 等主流构建工具。
+
+## 安装
+
+```bash
+npm install earthsdk3-assets
+```
+
+## 特性
+
+- 🔍 **自动检测构建工具** - 根据项目依赖自动选择对应插件
+- ⚡ **支持 Vite** - 原生 ESM，极速开发体验
+- 📦 **支持 Webpack** - 兼容 Webpack 5.x
+- 🚀 **支持 Rspack** - 字节跳动出品，Webpack API 兼容
+- 💾 **增量下载** - 智能缓存，只下载变更资源
+- 🎯 **零配置** - 开箱即用，自动注入脚本
+
+## 使用方法
+
+### 自动检测（推荐）
+
+插件会自动检测你项目使用的构建工具：
+
+#### 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/vite';
+
+// Webpack
+const earthsdkAssets = require('earthsdk3-assets/webpack');
+
+// Rspack
+const earthsdkAssets = require('earthsdk3-assets/rspack');
+```
+
+## 工作原理
+
+1. **资源下载** - 从远程服务器下载 EarthSDK3 所需的静态资源（图片、模型等）
+2. **智能缓存** - 使用 MD5 校验，只下载变更的文件
+3. **Dev Server** - 开发模式下提供 `/js` 路径的资源服务
+4. **产物拷贝** - 构建时将资源拷贝到 `dist/js` 目录
+5. **HTML 注入** - 自动在 HTML 中注入 `<script src="/js/earthsdk3-assets.js">`
+
+## 目录结构
+
+```
+earthsdk3-assets/
+├── src/
+│   ├── core/
+│   │   ├── downloadAssets.js    # 资源下载核心逻辑
+│   │   └── copyAssets.js        # 文件拷贝工具
+│   ├── plugins/
+│   │   ├── vite.js              # Vite 插件
+│   │   ├── webpack.js           # Webpack 插件
+│   │   └── rspack.js            # Rspack 插件
+│   ├── index.js                 # ESM 入口（自动检测）
+│   └── index.cjs                # CommonJS 入口
+├── assets/                      # 下载的静态资源
+├── earthsdk3-assets.js          # 资源加载器脚本
+└── package.json
+```
+
+## 构建工具检测优先级
+
+插件按以下顺序检测构建工具：
+
+1. **Vite** - 检查 `vite` 依赖或 `vite.config.*` 文件
+2. **Rspack** - 检查 `@rspack/core` 依赖或 `rspack.config.*` 文件
+3. **Webpack** - 检查 `webpack` 依赖或 `webpack.config.*` 文件
+
+## 注意事项
+
+- Webpack/Rspack 项目需要安装 `html-webpack-plugin` 或 `@rspack/plugin-html` 以支持 HTML 脚本注入
+- 所有构建工具插件均为可选依赖，未使用的构建工具不会引起报错
+
+## 许可证
+
+ISC

package/package.json

@@ -1,12 +1,28 @@
 {
     "name": "earthsdk3-assets",
-    "version": "3.0.14",
+    "version": "3.0.15",
     "description": "地球可视化实验室 (EarthSDK&CesiumLab) https://www.bjxbsj.cn",
     "private": false,
-    "main": "./earthsdk3Assets.js",
+    "type": "module",
+    "main": "./src/index.js",
+    "exports": {
+        ".": {
+            "import": "./src/index.js",
+            "require": "./src/index.cjs"
+        },
+        "./vite": {
+            "import": "./src/plugins/vite.js"
+        },
+        "./webpack": {
+            "require": "./src/plugins/webpack.js"
+        },
+        "./rspack": {
+            "require": "./src/plugins/rspack.js"
+        }
+    },
     "files": [
+        "src/",
         "earthsdk3-assets.js",
-        "earthsdk3Assets.js",
         "package.json"
     ],
     "scripts": {
@@ -17,5 +33,21 @@
     "author": "suplyang",
     "owner": "北京西部世界科技有限公司",
     "homepage": "www.earthsdk.com",
-    "license": "ISC"
-}
+    "license": "ISC",
+    "peerDependencies": {
+        "vite": ">=4.0.0",
+        "webpack": ">=5.0.0",
+        "@rspack/core": ">=0.5.0"
+    },
+    "peerDependenciesMeta": {
+        "vite": {
+            "optional": true
+        },
+        "webpack": {
+            "optional": true
+        },
+        "@rspack/core": {
+            "optional": true
+        }
+    }
+}

package/src/core/copyAssets.js

@@ -0,0 +1,39 @@
+import fs from 'fs';
+import path from 'path';
+
+const IGNORE_FILES = new Set(['.assets-version', '.assets-manifest.json']);
+
+export function copyAssetsToDest(assetsDir, rootDir, outDir) {
+    const dest = path.join(outDir, 'js');
+    fs.mkdirSync(dest, { recursive: true });
+
+    if (fs.existsSync(assetsDir)) {
+        fs.cpSync(assetsDir, path.join(dest, 'assets'), {
+            recursive: true,
+            filter(src) {
+                const baseName = path.basename(src);
+                if (IGNORE_FILES.has(baseName)) {
+                    return false;
+                }
+                if (baseName.endsWith('.download') || baseName.endsWith('.tmp')) {
+                    return false;
+                }
+                return true;
+            }
+        });
+    }
+
+    const sdkSrc = path.join(rootDir, 'earthsdk3-assets.js');
+    if (fs.existsSync(sdkSrc)) {
+        fs.cpSync(sdkSrc, path.join(dest, 'earthsdk3-assets.js'));
+    }
+
+    console.log('[earthsdk-assets] 资源已拷贝到:', dest);
+}
+
+export function getAssetsPaths(rootDir) {
+    const assetsDir = path.resolve(rootDir, 'assets');
+    const cacheFile = path.resolve(assetsDir, '.assets-version');
+    const manifestCacheFile = path.resolve(assetsDir, '.assets-manifest.json');
+    return { assetsDir, cacheFile, manifestCacheFile };
+}