EarthSDK3 Assets

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

安装

npm install earthsdk3-assets

特性

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

使用方法

自动检测（推荐）

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

Vite 项目

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

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

Webpack 项目

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

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

Rspack 项目

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

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

手动指定构建工具

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

// 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' })]
};

自定义配置

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

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

子路径导入

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

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

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

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

配置选项

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | 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. 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/                          # 下载的图片资源
├── 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，无需额外安装
• 所有构建工具插件均为可选依赖，未使用的构建工具不会引起报错
• 开发模式下资源通过虚拟路径访问，不创建物理文件到项目目录
• 生产模式下资源会根据清单文件拷贝到构建输出目录
• 内网环境下如果已有缓存，即使无法访问外网也能正常运行

许可证

ISC