
本文详解 Three.js 初学者常见问题:场景空白、仅显示标题——根源在于 importmap 中错误地将版本号包裹在 尖括号内,导致模块加载失败,浏览器控制台报错但易被忽略。
本文详解 three.js 初学者常见问题:场景空白、仅显示标题——根源在于 importmap 中错误地将版本号包裹在 `
当你严格按照官方文档搭建第一个 Three.js 应用,却只看到 <h1>My first three.js app</h1> 而不见绿色旋转立方体时,问题极可能出在 <script type="importmap"></script> 的版本写法上——这不是代码逻辑错误,而是典型的语法陷阱。
? 根本原因:importmap 版本号不能带尖括号
Three.js 官方文档示例中为强调占位符,有时会用 <v0.x.y></v0.x.y> 表示“此处填入实际版本”,但这 不是合法的 URL 组成部分。你在 index.html 中写了:
"three": "https://cdn.jsdelivr.net/npm/<v0.167.1>/build/three.module.js"
浏览器会尝试请求一个包含字面量 <v0.167.1></v0.167.1> 的 URL(如 https://cdn.jsdelivr.net/npm/%3Cv0.167.1%3E/...),自然 404,模块加载失败。控制台通常显示类似:
Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "text/html".
或更直接的:
一个基于官方 Mailtrap Node.js SDK 构建的 ASE 技能,用于发送事务邮件并与 Mailtrap 沙盒或生产流程协作。它非常适合需要 API 驱动邮件投递、测试邮箱验证和结构化消息自动化的代理工作流。
Uncaught TypeError: Failed to resolve module specifier "three". Relative references must start with either "/", "./", or "../".
✅ 正确写法:纯版本字符串,无符号包裹
只需移除 和 <code>>,使用标准语义化版本格式即可(推荐 0.167.1 或 v0.167.1,二者等效):
<script type="importmap">
{
"imports": {
"three": "https://cdn.jsdelivr.net/npm/three@0.167.1/build/three.module.js",
"three/addons/": "https://cdn.jsdelivr.net/npm/three@0.167.1/examples/jsm/"
}
}
</script>✅ 提示:CDN 支持
v0.167.1和0.167.1两种写法;但<v0.167.1></v0.167.1>是非法字符,必须删除。
? 推荐优化:内联脚本 + 版本锁定(避免未来兼容问题)
为快速验证并提升健壮性,建议将 main.js 内联至 HTML,并显式指定最新稳定版(截至 2024 年,0.167.1 仍广泛兼容)。完整修复后的 index.html 如下:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My first three.js app</title>
<style>body { margin: 0; }</style>
<script type="importmap">
{
"imports": {
"three": "https://cdn.jsdelivr.net/npm/three@0.167.1/build/three.module.js",
"three/addons/": "https://cdn.jsdelivr.net/npm/three@0.167.1/examples/jsm/"
}
}
</script>
</head>
<body>
<script type="module">
import * as THREE from 'three';
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(
75,
window.innerWidth / window.innerHeight,
0.1,
1000
);
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(window.devicePixelRatio);
document.body.appendChild(renderer.domElement);
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);
camera.position.z = 5;
// 使用 setAnimationLoop 替代手动 requestAnimationFrame 循环
renderer.setAnimationLoop(() => {
cube.rotation.x += 0.01;
cube.rotation.y += 0.01;
renderer.render(scene, camera);
});
// 响应窗口大小变化
window.addEventListener('resize', () => {
camera.aspect = window.innerWidth / window.innerHeight;
camera.updateProjectionMatrix();
renderer.setSize(window.innerWidth, window.innerHeight);
});
</script>
</body>
</html>⚠️ 其他关键注意事项
-
确保使用本地服务器预览:直接双击
index.html会因跨域限制导致模块加载失败。请用npx serve、VS Code Live Server 插件或python3 -m http.server启动 HTTP 服务。 -
检查浏览器支持:
importmap需 Chrome 89+ / Firefox 109+ / Safari 16.4+;旧版浏览器需改用构建工具(如 Vite)或<script type="module"></script>直接引入 CDN URL。 -
启用抗锯齿与设备像素比:添加
antialias: true和setPixelRatio()可显著提升渲染质量,这是生产环境必备实践。
✅ 总结
Three.js “白屏”问题 80% 源于环境配置而非渲染逻辑。牢记:
? importmap 中的版本号是 URL 路径的一部分,禁止添加 符号;
? 始终通过本地服务器运行;
? 善用浏览器开发者工具 → Console 和 Network 标签页,第一时间定位 404 或 CORS 错误。
修复后,你将立即看到一个平滑旋转的绿色立方体——这才是 Three.js 旅程真正开始的地方。

















