本文详解如何通过现代 es 模块方式，借助 unpkg 或 jsdelivr cdn 在浏览器中正确加载 three.js 的 `stlloader` 并渲染 `.stl` 文件，规避常见模块导入错误与路径陷阱。
在 Three.js 生态中，STLLoader 并非独立发布的 NPM 包（如 three-stl-loader），而是官方维护的 examples/jsm（ES Module 版示例库）的一部分。因此，直接通过 <script type="importmap"> 引入第三方压缩版 STLLoader.min.js（如 jsDelivr 上的旧版 UMD 文件）会导致 Uncaught SyntaxError: The requested module 'stl-loader' does not provide an export named 'STLLoader' —— 根本原因在于：该文件是 UMD/全局变量格式，不支持 import { STLLoader } from 'stl-loader' 这类原生 ES 模块语法。</script>
✅ 正确做法：统一使用 Three.js 官方托管的 ESM 兼容版本，即从 https://unpkg.com/three@X.X.X/examples/jsm/loaders/STLLoader.js 导入（推荐稳定版本如 0.154.0 或最新 ^0.160.0）。
以下是可直接运行的完整 HTML 示例（已修复所有关键问题）：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<title>Three.js + STL Loader（CDN ESM 方式）</title>
<style>body { margin: 0; overflow: hidden; }</style>
</head>
<body>
<!-- 启用 import maps 支持（现代浏览器兼容） -->
<script async src="https://unpkg.com/es-module-shims@2/dist/es-module-shims.js"></script>
<script type="importmap">
{
"imports": {
"three": "https://unpkg.com/three@0.160.0/build/three.module.js",
"three/addons/": "https://unpkg.com/three@0.160.0/examples/jsm/"
}
}
</script>
<script type="module">
import * as THREE from 'three';
import { STLLoader } from 'three/addons/loaders/STLLoader.js'; // ✅ 正确路径：ESM 原生导出
// --- 场景基础设置 ---
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, 0.6);
scene.add(ambientLight);
const directionalLight = new THREE.DirectionalLight(0xffffff, 0.8);
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/slotted_disk.stl', // 示例在线 STL
(geometry) => {
const material = new THREE.MeshPhongMaterial({
color: 0xaaaaaa,
specular: 0x111111,
shininess: 200,
flatShading: true
});
const mesh = new THREE.Mesh(geometry, material);
mesh.castShadow = true;
mesh.receiveShadow = true;
mesh.scale.set(10, 10, 10);
mesh.position.y = -5;
geometry.center(); // 居中几何体，便于观察
scene.add(mesh);
},
(progress) => {
console.log(`加载中: ${(progress.loaded / progress.total * 100).toFixed(1)}%`);
},
(error) => {
console.error('STL 加载失败:', error);
}
);
// --- 动画循环 ---
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>? 关键注意事项：
- ✅ 必须使用 three/addons/loaders/STLLoader.js（非 .min.js）：只有该路径提供标准 ESM 导出（export { STLLoader }），.min.js 是为 script 标签设计的 UMD 构建，无法被 import 解析。
- ✅ importmap 中 three/addons/ 的映射必须精确到 /examples/jsm/ 目录，后续 import ... from 'three/addons/...' 才能正确解析子路径。
- ✅ STL 渲染依赖光照：若未添加 AmbientLight 或 DirectionalLight，模型将呈现纯黑（因 .stl 仅含几何数据，无材质/法线信息，需光照计算明暗）。
- ⚠️ 本地文件限制：直接双击打开 HTML 时，浏览器会因 CORS 禁止加载本地 file:// STL 文件；务必通过本地服务器（如 npx serve、VS Code Live Server）或使用 GitHub Raw 链接（如示例所示）。
- ? 版本一致性：确保 three 主包与 addons 路径中的版本号一致（如都用 0.160.0），避免 API 不兼容。
总结：Three.js 的 STLLoader 是官方 examples 库的组成部分，不是独立模块。拥抱 ESM、使用 unpkg.com/three@X.X.X/examples/jsm/ 路径，是 CDN 方式下最简洁、可靠且面向未来的集成方案。
