本文详解如何通过 cdn 在纯 html 环境中正确使用 three.js 的 `stlloader` 加载 `.stl` 文件，重点解决 es6 模块导入错误、路径配置失效及常见白屏问题。
在 Three.js 生态中，STLLoader 并非独立发布的 NPM 包（如 stl-loader），而是作为官方 three 仓库的 内置扩展模块（ESM） 存在于 examples/jsm/loaders/STLLoader.js 路径下。你当前代码中尝试从 https://cdn.jsdelivr.net/npm/three@0.154.0/examples/jsm/loaders/STLLoader.min.js 导入，但该路径实际并不存在（STLLoader.min.js 是旧版 UMD 构建产物，不支持 import { STLLoader } from '...' 语法），导致报错：
Uncaught SyntaxError: The requested module 'stl-loader' does not provide an export named 'STLLoader'
✅ 正确做法是：统一使用官方 three 的 ESM 示例模块 CDN 地址，并通过 importmap 映射 three/addons/ 到对应路径，再按标准方式导入。
以下是可直接运行的完整示例（已验证兼容 Three.js v0.154+）：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<title>Three.js STL Loader 示例</title>
<style>body { margin: 0; overflow: hidden; }</style>
</head>
<body>
<!-- 启用 importmap 支持（现代浏览器原生支持） -->
<script type="importmap">
{
"imports": {
"three": "https://unpkg.com/three@0.154.0/build/three.module.js",
"three/addons/": "https://unpkg.com/three@0.154.0/examples/jsm/"
}
}
</script>
<script type="module">
import * as THREE from 'three';
import { STLLoader } from 'three/addons/loaders/STLLoader.js';
// 基础场景设置
const scene = new THREE.Scene();
scene.background = new THREE.Color(0xcc0000);
const camera = new THREE.PerspectiveCamera(
75,
window.innerWidth / window.innerHeight,
0.1,
1000
);
camera.position.z = 20;
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.shadowMap.enabled = true;
document.body.appendChild(renderer.domElement);
// 添加基础光照（STL 渲染必需）
const ambientLight = new THREE.AmbientLight(0xffffff, 1.2);
scene.add(ambientLight);
const directionalLight = new THREE.DirectionalLight(0xffffff, 1);
directionalLight.position.set(5, 5, 5);
directionalLight.castShadow = true;
scene.add(directionalLight);
// 加载 STL 模型
const loader = new STLLoader();
loader.load(
'https://raw.githubusercontent.com/mrdoob/three.js/master/examples/models/stl/binary/dolphins.stl', // 示例在线 STL
(geometry) => {
const material = new THREE.MeshPhongMaterial({
color: 0xaaaaaa,
specular: 0x111111,
shininess: 200
});
const mesh = new THREE.Mesh(geometry, material);
mesh.castShadow = true;
mesh.receiveShadow = true;
// 居中并缩放适配视图
const box = new THREE.Box3().setFromObject(mesh);
mesh.position.sub(box.getCenter());
mesh.scale.setScalar(5 / Math.max(...box.getSize()));
scene.add(mesh);
},
undefined,
(err) => console.error('STL 加载失败:', err)
);
// 动画循环
function animate() {
requestAnimationFrame(animate);
renderer.render(scene, camera);
}
animate();
// 响应式调整
window.addEventListener('resize', () => {
camera.aspect = window.innerWidth / window.innerHeight;
camera.updateProjectionMatrix();
renderer.setSize(window.innerWidth, window.innerHeight);
});
</script>
</body>
</html>? 关键要点说明：
- ✅ 路径必须精确：STLLoader 的 ESM 版本路径为 'three/addons/loaders/STLLoader.js'（注意 .js 后缀不可省略），而非 STLLoader.min.js 或任意第三方包。
- ✅ 依赖光照：STL 文件无材质信息，必须添加 AmbientLight + DirectionalLight 等光源，否则模型将全黑或不可见。
- ✅ 几何体居中与缩放：.stl 坐标常偏移且单位不一，建议用 Box3.setFromObject() 自动计算中心与尺寸后校正位置和缩放。
- ⚠️ CORS 注意事项：本地直接双击打开 HTML 会因文件协议（file://）触发跨域限制；请使用本地服务器（如 VS Code Live Server 插件、npx serve）或托管至支持 CORS 的 URL（如 GitHub Raw 链接）。
- ? CDN 版本一致性：确保 three 主库与 addons 路径版本号严格一致（如 @0.154.0），避免 API 不兼容。
? 总结：放弃所有非官方 stl-loader 第三方 CDN，坚持使用 unpkg.com/three@X.X.X/examples/jsm/... 这一权威路径，配合标准 ESM 导入与基础渲染配置，即可稳定加载 STL 模型。这是目前最轻量、零构建、开箱即用的方案。
