本文介绍在 Webpack 构建的模块化项目中，无缝迁移传统全局依赖型 THREE.js 插件（如自定义 THREE.EVALoader）的方法，通过显式挂载 THREE 到全局作用域，复用原有代码逻辑，最小化改造成本。
本文介绍在 webpack 构建的模块化项目中，无缝迁移传统全局依赖型 three.js 插件（如自定义 `three.evaloader`）的方法，通过显式挂载 `three` 到全局作用域，复用原有代码逻辑，最小化改造成本。
在将遗留的 THREE.js 项目（依赖 <script> 全局注入）迁移到现代模块化开发流程（如 Webpack + ES Module）时，核心挑战在于：*原项目大量插件（如 EVALoader.js、EVAPreviews.js）直接向全局 THREE 对象挂载方法或属性（THREE.EVALoader = ...），而标准 `import as THREE from 'three'` 仅提供只读命名空间，无法动态扩展**。
直接在模块中 import THREE from 'three' 后尝试 THREE.EVALoader = ... 会失败——因为 ES 模块导出是静态且不可变的。解决方案不是“绕过模块系统”，而是主动、可控地重建全局 THREE 引用，使其既满足模块依赖，又兼容原有扩展逻辑。
✅ 推荐实践：统一初始化全局 THREE
创建 src/globals.js（或 src/three-init.js）作为项目 THREE 入口：
// src/globals.js
import * as THREE from 'three';
// 关键：将 THREE 显式挂载到 globalThis（浏览器中为 window，Node 中为 global）
// 使用 globalThis 兼容性更好，比 window 或 global 更健壮
globalThis.THREE = THREE;
// 可选：为自定义扩展创建独立命名空间，避免污染 THREE 原生对象
globalThis.EVA = {
version: '1.0.0',
// 可在此集中管理 EVA 相关工具类
};
console.debug('✅ THREE initialized globally:', globalThis.THREE);
console.debug('✅ EVA namespace ready:', globalThis.EVA);
export default THREE;? 为什么用 globalThis.THREE？
- globalThis 是 ECMAScript 2019 标准，统一了浏览器（window）、Node.js（global）、Web Worker（self）等环境的全局对象访问方式，避免环境判断。
- Webpack 打包后，globalThis.THREE 在浏览器中即为 window.THREE，与原始 HTML 中 <script src="three.min.js"> 的行为完全一致。
? 改写插件文件（如 EVALoader.js）
无需修改原有逻辑结构，只需确保其在 globals.js 之后执行（Webpack 会按 import 顺序解析）：
// src/EVALoader.js
// 注意：此处 import 的是全局 THREE，而非重新引入 three 包
// 因此可安全扩展
if (typeof globalThis.THREE === 'undefined') {
throw new Error('THREE is not available globally. Import globals.js first.');
}
const { EVALoader } = globalThis.THREE;
// 若 EVALoader 尚未定义，则注册
if (!EVALoader) {
globalThis.THREE.EVALoader = class EVALoader {
constructor(onLoad, url, options = {}) {
// ✅ 此处可完全复用原逻辑
console.log('EVALoader instantiated with:', { url, options });
// ... 实际加载逻辑
}
};
}⚠️ 重要注意事项
导入顺序至关重要：在 index.js（入口文件）中，必须最先导入 globals.js，再导入所有依赖 THREE 扩展的插件：
// src/index.js —— 必须放在最顶部 import './globals.js'; // ✅ 确保 THREE 已挂载 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls'; import './EVALoader.js'; import './EVAPreviews.js'; import './EVAOptions.js'; // 后续业务代码... const scene = new THREE.Scene(); const loader = new THREE.EVALoader(() => {}, '/model.glb'); // ✅ 可直接使用避免重复挂载：在插件中加入存在性检查（如 if (!THREE.EVALoader)），防止多次 HMR 热更新导致重复定义报错。
Tree-shaking 影响：globalThis.THREE = THREE 不影响 three 包自身的 tree-shaking；你仍可通过 import { Mesh, BoxGeometry } from 'three' 按需引入，保持打包体积精简。
? 补充：兼容官方示例插件（如 OrbitControls）
对于 OrbitControls 等官方插件，推荐继续使用标准模块导入，无需挂载到全局：
import * as THREE from 'three';
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls';
// ✅ 官方插件已导出构造函数，直接使用
const controls = new OrbitControls(camera, renderer.domElement);这与 EVALoader 的“全局扩展”模式并行不悖——前者是消费型模块，后者是增强型补丁，二者职责清晰。
✅ 总结
| 场景 | 推荐方式 | 说明 |
|---|---|---|
| 原生 THREE 核心 | import * as THREE from 'three' + globalThis.THREE = THREE | 建立全局引用，支撑旧插件扩展 |
| 自定义插件（EVALoader 等） | 直接操作 globalThis.THREE | 复用原有 THREE.XXX = ... 语法，零逻辑修改 |
| 官方示例插件 | import { X } from 'three/examples/jsm/...' | 标准 ES 模块消费，更安全、可 tree-shake |
| 入口文件 | import './globals.js' 作为第一行 | 保证全局环境就绪 |
该方案在不重构原有插件逻辑的前提下，实现了平滑迁移，兼顾可维护性与向后兼容性，是渐进式现代化升级的理想起点。
