简介three.js-r137.zip 是为前端开发者准备的 three.js r137 版本资料集聚焦 WebGL 3D 渲染技术帮助读者快速掌握在浏览器中构建三维场景的方法。压缩包共 2000 个文件约 306.64MB以 JS 源码和 HTML 示例为主同时收录大量纹理贴图jpg/png、模型文件gltf/glb/obj、样式与文档便于对照学习和二次开发目前已有 190 人学习/下载。内容系统梳理了场景、相机、灯光、材质、纹理等核心概念并涵盖 r137 版本在渲染性能、阴影处理、几何体扩展和动画控制上的改进适合从零基础到进阶的前端开发者用于 3D 产品展示、游戏开发、数据可视化等方向。通过编译运行内置示例可以直观理解 API 调用与调试要点快速上手并缩短开发调试周期。1. three.js-r137.zip 不只是一个离线包而是一个被锁定的渲染环境很多工程师拿到three.js-r137.zip后的第一反应是解压、找index.html、双击、希望看到 3D 场景。实际维护老系统或做离线交付时这个 zip 锁住的并不是文件而是一整套 WebGL 渲染边界。r137 发布时正好处在 ES Module 普及和传统script标签并存的过渡期所以同一份压缩包里既有three.min.js这种全局式构建也有three.module.js这种模块化入口。对正在接手旧版数字孪生项目、在内网环境做three.js 下载后离线开发或者需要照着旧教程复现效果的工程师来说这个包比npm install three更可控版本不会因为依赖解析悄悄改变连带examples/jsm下的扩展模块路径也固定在同一天。先花 10 分钟搞清 r137 的边界比急着升级或抄新代码更值得。2. 解开 three.js-r137.zip先跑通 ES Module 本地服务拿到包之后我一般先不看 3D 示例而是先把目录结构和加载方式确认清楚。GitHub 下载的 zip 包不需要安装解压后把该目录当作静态站点根目录就行。r137 的 release 包中通常能看到这样的结构three.js-r137/ build/ three.min.js three.module.js examples/ jsm/ controls/ loaders/ src/ package.jsonbuild/three.module.js是模块化开发的入口build/three.min.js是老式全局引入用的。package.json里的 version 可以辅助核对但最准的是运行时读取THREE.REVISION。examples/jsm是 r137 的扩展模块目录里面是OrbitControls、GLTFLoader等后面章节会用到。2.1 先起本地静态服务不要双击 index.html如果你在 3D 页面里用了任何script typemodule或new Worker浏览器在file://协议下都会拦截跨域请求直接双击打开的页面大概率只有一片空白控制台里出现 CORS 报错。所以本地开发的第一步是起一个 HTTP 服务cd three.js-r137 python3 -m http.server 8080如果你没有 Python只有 Node.js也可以执行npx serve -l 8080。两种方式都是把当前目录暴露到本机 8080 端口页面里的相对路径从根目录开始计算。之后访问http://localhost:8080。2.2 用 importmap 把 three 映射到本地文件r137 的模块化页面可以直接用script typeimportmap这是不需要打包器就能在浏览器里解析three模块的方法。在静态目录下建一个index.html!doctype html html langzh-CN head meta charsetutf-8 / titler137 启动页/title style html, body { margin: 0; height: 100%; background: #111; } /style /head body script typeimportmap { imports: { three: ./build/three.module.js } } /script script typemodule import * as THREE from three; document.title three.js r THREE.REVISION; /script /body /html这段代码做了三件事用importmap声明 bare import 名称three对应本地文件用typemodule启用 ES Module 解析把THREE.REVISION写到页面标题上。当标题显示three.js r137时说明模块链路已经通了。如果标题不变优先检查浏览器网络面板里.module.js请求是否 404或者是否有 CORS 错误。这里有个关键点importmap里build/three.module.js前面的./不能省否则浏览器会拿它当作绝对路径请求。如果你的项目后续要部署到子路径还必须把这里改成基于import.meta.url的动态相对路径否则子目录部署就会失效。2.3 全局式 three.min.js 和模块化的取舍老项目的three.js 教程常见写法是script src./build/three.min.js/script后用全局THREE。这种用法在 r137 里依然可用区别主要是工程化和按需加载。把两种方式放在一起看引入方式适用场景是否依赖 HTTP 服务主要局限script srcthree.min.js遗留页面、快速 Demo普通 script 可以 file 打开但纹理/模型加载仍受限全局命名空间扩展模块要额外 scriptimportmap three.module.js新页面、离线包集成必须 HTTP 服务需要写 importmap浏览器支持有版本要求npm 包webpack/vite 工程不依赖package-lock 锁版本内网需要镜像缓存实际维护中如果只是画一个不会损坏的浮动物体全局式更快如果后面要接OrbitControls、GLTFLoader这些examples/jsm里的模块推荐直接用 importmap因为examples/jsm内部大量使用import语法普通script无法直接消化。3. r137 最小可运行场景renderer / scene / camera 的初始化顺序本地服务跑通之后下一步不是急着写大场景而是用一个旋转立方体验证渲染管线。很多报错不是 three.js 本身的问题而是初始化顺序错了。下面这段代码是我在 r137 上常用的最小模板。3.1 直接可贴的旋转立方体代码import * as THREE from three; import { OrbitControls } from ./examples/jsm/controls/OrbitControls.js; const container document.querySelector(#app); const width container.clientWidth; const height container.clientHeight; // 1. renderer 先创建确保 canvas 就绪 const renderer new THREE.WebGLRenderer({ antialias: true }); renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); renderer.setSize(width, height); container.appendChild(renderer.domElement); // 2. scene 与 camera注意 camera 是透视相机 const scene new THREE.Scene(); scene.background new THREE.Color(0x111122); const camera new THREE.PerspectiveCamera( 50, width / height, 0.1, 1000 ); camera.position.set(3, 2, 5); camera.lookAt(0, 0, 0); // 3. 添加几何体、材质、灯光 const box new THREE.Mesh( new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial({ color: 0x33aaff, roughness: 0.4, metalness: 0.1 }) ); scene.add(box); const ambient new THREE.AmbientLight(0xffffff, 0.6); scene.add(ambient); const dirLight new THREE.DirectionalLight(0xffffff, 1.2); dirLight.position.set(3, 4, 2); scene.add(dirLight); // 4. OrbitControls 接管相机交互 const controls new OrbitControls(camera, renderer.domElement); controls.target.set(0, 0, 0); controls.enableDamping true; // 5. 动画循环 const clock new THREE.Clock(); function animate() { requestAnimationFrame(animate); const elapsed clock.getElapsedTime(); box.rotation.x elapsed * 0.5; box.rotation.y elapsed * 0.8; controls.update(); renderer.render(scene, camera); } animate(); // 6. 窗口自适应 window.addEventListener(resize, () { const w container.clientWidth; const h container.clientHeight; camera.aspect w / h; camera.updateProjectionMatrix(); renderer.setSize(w, h); });代码中的顺序是刻意安排的WebGLRenderer必须先创建并拿到domElement后续OrbitControls才能把它作为交互挂载点。PerspectiveCamera的四个参数分别是fov、aspect、near、farfov 越小越接近长焦项目里常用 45 到 60near 和 far 一般设到 0.1 和 1000 就够用太小的 near 会引发深度精度问题。灯光部分AmbientLight提供基础亮度DirectionalLight提供方向阴影用的硬光。MeshStandardMaterial对粗糙度和金属度敏感r137 中roughness越高反光越弱metalness越高越接近导体材质。如果场景只有环境光立方体会显得很平所以通常要补一个方向光。controls.enableDamping true会让相机在停止拖动后还有一段惯性滑动但必须配合动画循环里的controls.update()。忘记这一步是惯性控制不生效的最常见原因。3.2 r137 材质发灰时先检查 outputEncoding上面的代码跑起来后很多同事的第一个反馈是蓝色材质比设计稿暗一截。这不是显示设备的问题而是 r137 默认没有做 sRGB 输出转换。修复方法是在 renderer 创建后加两行renderer.outputEncoding THREE.sRGBEncoding;如果用了外部的 albedo 贴图还需要对贴图单独标记const texture new THREE.TextureLoader().load(texture.png); texture.encoding THREE.sRGBEncoding;这个 API 在 r137 里是有效的但到了 r150 以后outputEncoding被outputColorSpace替代枚举也从THREE.sRGBEncoding变成THREE.SRGBColorSpace。如果你在搜three.js新版代码时直接复制outputColorSpace到 r137 里会得到 undefined。反之把旧代码sRGBEncoding粘到新版工程里也会失效。这是 r137 和现代版本之间最常见的兼容地雷放到后面第 5 章的检查清单里专门验证。4. r137 离线包接入数字孪生工程examples/jsm 的加载路径与依赖方式three.js-r137.zip最有价值的地方在于它完整保留了examples/jsm目录在离线环境里可以直接引用OrbitControls、GLTFLoader等官方扩展。这在工业数字孪生项目中非常常见系统部署在隔离内网不能在线拉取 CDN也没有 npm 私有仓库一个 zip 包就是唯一的依赖来源。4.1 importmap 与 examples/jsm 的依赖关系examples/jsm下的模块分散在controls/、loaders/、objects/等子目录里模块之间常用相对路径互相引用也会引用three这个 bare import。比如 r137 的OrbitControls.js顶部可能是import { ... } from three;。如果你在自己的工程里直接 import 这个文件但页面没有定义 importmap浏览器无法把three解析成一个 URL会报 “Failed to resolve module specifier”。所以在使用 zip 包内的任何 jsm 扩展前必须先在入口 HTML 里定义统一的 importmap{ imports: { three: ./build/three.module.js } }这样examples/jsm/controls/OrbitControls.js内部的import ... from three才能命中同一个three.module.js。注意这里的three映射一定要指向模块版本而不是three.min.js因为 min 版本不是 ES Module无法被 import 语法复用。4.2 不放心时先查模块内部 import 了谁拿到陌生 zip 包时我习惯先查一下它的真实依赖而不是猜。进入解压目录后执行cd three.js-r137 grep -Rho from .* examples/jsm | sed s/from // | sort -u这段命令把examples/jsm下所有 ES Module 引用的来源粗略列出来。输出里如果出现from three说明依赖顶层 importmap如果出现from ./xxx.js或from ../xxx.js说明它依赖 zip 包内的相对文件。看到路径后用ls对照一下对应文件是否存在就能在编码前排除缺失依赖的问题。如果拿到的是一个从 GitHub 页面直接下载的源码 zip有时examples/jsm里的依赖会指向../../examples/fonts这类资源目录。只要整个 zip 都在相对路径不会断真正容易断的是你把jsm某个文件单独复制到项目里却没有带上它引用的兄弟文件。4.3 在 r137 里加载一个 GLB 模型下面是接入模型加载的最小片段。这里我假设你已经把模型放在站点根目录的models/下。import * as THREE from three; import { GLTFLoader } from ./examples/jsm/loaders/GLTFLoader.js; import { OrbitControls } from ./examples/jsm/controls/OrbitControls.js; const container document.querySelector(#app); const renderer new THREE.WebGLRenderer({ antialias: true, alpha: true }); renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); renderer.setSize(container.clientWidth, container.clientHeight); container.appendChild(renderer.domElement); const scene new THREE.Scene(); const camera new THREE.PerspectiveCamera( 45, container.clientWidth / container.clientHeight, 0.1, 2000 ); camera.position.set(10, 8, 10); const controls new OrbitControls(camera, renderer.domElement); controls.enableDamping true; scene.add(new THREE.AmbientLight(0xffffff, 0.8)); const dirLight new THREE.DirectionalLight(0xffffff, 1.5); dirLight.position.set(5, 10, 7); scene.add(dirLight); const loader new GLTFLoader(); loader.load( ./models/room.glb, (gltf) { scene.add(gltf.scene); const box new THREE.Box3().setFromObject(gltf.scene); const center box.getCenter(new THREE.Vector3()); controls.target.copy(center); }, undefined, (err) console.error(GLTF 加载失败, err) ); function animate() { requestAnimationFrame(animate); controls.update(); renderer.render(scene, camera); } animate();代码里renderer增加了alpha: true这样页面背景能透明方便和cesium等底图合成的工业数字孪生页面做叠加。GLTFLoader的load回调里用Box3计算模型包围盒再把相机控制目标移动到模型中心避免模型偏在原点外看不全。GLTF 加载失败分支里最常见的错误是本地模型路径 404或者纹理文件路径对不上先看 Network 面板别急着改代码。4.4 三种获取 three.js 的方式怎么选把前面的选型汇总成一张表对带离线限制的项目尤其有用来源版本锁定离线可用工程化便利度注意点CDN 引入URL 中版本号否低内网不可用版本不可控npm 安装package-lock需要镜像缓存高升级时副作用大zip importmap物理文件是中需要自行管理静态服务路径在 r137 这个版本下alpha: true的透明背景页面往往是最先被用到的集成点。要注意WebGLRenderer的alpha打开后如果还用scene.background设置不透明颜色透明效果会被覆盖。常见做法是让页面背景由外层 DOM/Cesium 决定three.js 场景里不设置 background。5. 拿到 three.js-r137.zip 后先做三次检查版本、依赖与颜色空间最后用一个 10 分钟能做完的检查流程收住这个主题。每次拿到陌生 zip 包或在 r137 工程里排查问题时我按顺序做下面三件事。5.1 验证 REVISION 而不是目录名package.json和文件夹名都可以被改但运行时版本号不会骗人。在页面控制台执行import * as THREE from three; console.log(THREE.REVISION);输出137就说明页面加载的就是 r137。如果输出了别的数字说明你虽然拿着 r137 的 zip但实际项目引用了另一个构建文件。反过来如果项目已经混入了新版本THREE.REVISION会立刻暴露问题。5.2 用 grep 列出扩展模块的依赖路径从 GitHub 下载的 zip 包大多数是完整的但手动拷贝examples/jsm下的单个文件时很容易漏掉兄弟文件。在解压后的根目录执行cd three.js-r137 grep -Rho from .* examples/jsm | sed s/from // | sort -u如果输出里只有three和../、./开头的路径你可以按路径逐个确认。所有相对路径的目标都要存在于 zip 包内否则浏览器会在运行时 404。这个命令不关注from three因为那是 importmap 的职责范围。5.3 颜色空间回归新老 API 的判断r137 代码里用renderer.outputEncoding THREE.sRGBEncoding;是合法写法。但在代码里做一次防御性判断可以避免未来迁移时炸掉if (THREE.ColorManagement ! undefined) { renderer.outputColorSpace THREE.SRGBColorSpace; } else { renderer.outputEncoding THREE.sRGBEncoding; }这个判断依据是THREE.ColorManagement是否存在r150 有它r137 没有。这样同一份页面在 r137 和现代版本下都能得到正确的 sRGB 输出。把这段逻辑放到渲染器初始化末尾再配合THREE.REVISION的检查r137 包是否真的生效、扩展模块是否完整、颜色是否走对三件事就都验证完了。本文还有配套的精品资源点击获取
简介three.js-r137.zip 是为前端开发者准备的 three.js r137 版本资料集聚焦 WebGL 3D 渲染技术帮助读者快速掌握在浏览器中构建三维场景的方法。压缩包共 2000 个文件约 306.64MB以 JS 源码和 HTML 示例为主同时收录大量纹理贴图jpg/png、模型文件gltf/glb/obj、样式与文档便于对照学习和二次开发目前已有 190 人学习/下载。内容系统梳理了场景、相机、灯光、材质、纹理等核心概念并涵盖 r137 版本在渲染性能、阴影处理、几何体扩展和动画控制上的改进适合从零基础到进阶的前端开发者用于 3D 产品展示、游戏开发、数据可视化等方向。通过编译运行内置示例可以直观理解 API 调用与调试要点快速上手并缩短开发调试周期。1. three.js-r137.zip 不只是一个离线包而是一个被锁定的渲染环境很多工程师拿到three.js-r137.zip后的第一反应是解压、找index.html、双击、希望看到 3D 场景。实际维护老系统或做离线交付时这个 zip 锁住的并不是文件而是一整套 WebGL 渲染边界。r137 发布时正好处在 ES Module 普及和传统script标签并存的过渡期所以同一份压缩包里既有three.min.js这种全局式构建也有three.module.js这种模块化入口。对正在接手旧版数字孪生项目、在内网环境做three.js 下载后离线开发或者需要照着旧教程复现效果的工程师来说这个包比npm install three更可控版本不会因为依赖解析悄悄改变连带examples/jsm下的扩展模块路径也固定在同一天。先花 10 分钟搞清 r137 的边界比急着升级或抄新代码更值得。2. 解开 three.js-r137.zip先跑通 ES Module 本地服务拿到包之后我一般先不看 3D 示例而是先把目录结构和加载方式确认清楚。GitHub 下载的 zip 包不需要安装解压后把该目录当作静态站点根目录就行。r137 的 release 包中通常能看到这样的结构three.js-r137/ build/ three.min.js three.module.js examples/ jsm/ controls/ loaders/ src/ package.jsonbuild/three.module.js是模块化开发的入口build/three.min.js是老式全局引入用的。package.json里的 version 可以辅助核对但最准的是运行时读取THREE.REVISION。examples/jsm是 r137 的扩展模块目录里面是OrbitControls、GLTFLoader等后面章节会用到。2.1 先起本地静态服务不要双击 index.html如果你在 3D 页面里用了任何script typemodule或new Worker浏览器在file://协议下都会拦截跨域请求直接双击打开的页面大概率只有一片空白控制台里出现 CORS 报错。所以本地开发的第一步是起一个 HTTP 服务cd three.js-r137 python3 -m http.server 8080如果你没有 Python只有 Node.js也可以执行npx serve -l 8080。两种方式都是把当前目录暴露到本机 8080 端口页面里的相对路径从根目录开始计算。之后访问http://localhost:8080。2.2 用 importmap 把 three 映射到本地文件r137 的模块化页面可以直接用script typeimportmap这是不需要打包器就能在浏览器里解析three模块的方法。在静态目录下建一个index.html!doctype html html langzh-CN head meta charsetutf-8 / titler137 启动页/title style html, body { margin: 0; height: 100%; background: #111; } /style /head body script typeimportmap { imports: { three: ./build/three.module.js } } /script script typemodule import * as THREE from three; document.title three.js r THREE.REVISION; /script /body /html这段代码做了三件事用importmap声明 bare import 名称three对应本地文件用typemodule启用 ES Module 解析把THREE.REVISION写到页面标题上。当标题显示three.js r137时说明模块链路已经通了。如果标题不变优先检查浏览器网络面板里.module.js请求是否 404或者是否有 CORS 错误。这里有个关键点importmap里build/three.module.js前面的./不能省否则浏览器会拿它当作绝对路径请求。如果你的项目后续要部署到子路径还必须把这里改成基于import.meta.url的动态相对路径否则子目录部署就会失效。2.3 全局式 three.min.js 和模块化的取舍老项目的three.js 教程常见写法是script src./build/three.min.js/script后用全局THREE。这种用法在 r137 里依然可用区别主要是工程化和按需加载。把两种方式放在一起看引入方式适用场景是否依赖 HTTP 服务主要局限script srcthree.min.js遗留页面、快速 Demo普通 script 可以 file 打开但纹理/模型加载仍受限全局命名空间扩展模块要额外 scriptimportmap three.module.js新页面、离线包集成必须 HTTP 服务需要写 importmap浏览器支持有版本要求npm 包webpack/vite 工程不依赖package-lock 锁版本内网需要镜像缓存实际维护中如果只是画一个不会损坏的浮动物体全局式更快如果后面要接OrbitControls、GLTFLoader这些examples/jsm里的模块推荐直接用 importmap因为examples/jsm内部大量使用import语法普通script无法直接消化。3. r137 最小可运行场景renderer / scene / camera 的初始化顺序本地服务跑通之后下一步不是急着写大场景而是用一个旋转立方体验证渲染管线。很多报错不是 three.js 本身的问题而是初始化顺序错了。下面这段代码是我在 r137 上常用的最小模板。3.1 直接可贴的旋转立方体代码import * as THREE from three; import { OrbitControls } from ./examples/jsm/controls/OrbitControls.js; const container document.querySelector(#app); const width container.clientWidth; const height container.clientHeight; // 1. renderer 先创建确保 canvas 就绪 const renderer new THREE.WebGLRenderer({ antialias: true }); renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); renderer.setSize(width, height); container.appendChild(renderer.domElement); // 2. scene 与 camera注意 camera 是透视相机 const scene new THREE.Scene(); scene.background new THREE.Color(0x111122); const camera new THREE.PerspectiveCamera( 50, width / height, 0.1, 1000 ); camera.position.set(3, 2, 5); camera.lookAt(0, 0, 0); // 3. 添加几何体、材质、灯光 const box new THREE.Mesh( new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial({ color: 0x33aaff, roughness: 0.4, metalness: 0.1 }) ); scene.add(box); const ambient new THREE.AmbientLight(0xffffff, 0.6); scene.add(ambient); const dirLight new THREE.DirectionalLight(0xffffff, 1.2); dirLight.position.set(3, 4, 2); scene.add(dirLight); // 4. OrbitControls 接管相机交互 const controls new OrbitControls(camera, renderer.domElement); controls.target.set(0, 0, 0); controls.enableDamping true; // 5. 动画循环 const clock new THREE.Clock(); function animate() { requestAnimationFrame(animate); const elapsed clock.getElapsedTime(); box.rotation.x elapsed * 0.5; box.rotation.y elapsed * 0.8; controls.update(); renderer.render(scene, camera); } animate(); // 6. 窗口自适应 window.addEventListener(resize, () { const w container.clientWidth; const h container.clientHeight; camera.aspect w / h; camera.updateProjectionMatrix(); renderer.setSize(w, h); });代码中的顺序是刻意安排的WebGLRenderer必须先创建并拿到domElement后续OrbitControls才能把它作为交互挂载点。PerspectiveCamera的四个参数分别是fov、aspect、near、farfov 越小越接近长焦项目里常用 45 到 60near 和 far 一般设到 0.1 和 1000 就够用太小的 near 会引发深度精度问题。灯光部分AmbientLight提供基础亮度DirectionalLight提供方向阴影用的硬光。MeshStandardMaterial对粗糙度和金属度敏感r137 中roughness越高反光越弱metalness越高越接近导体材质。如果场景只有环境光立方体会显得很平所以通常要补一个方向光。controls.enableDamping true会让相机在停止拖动后还有一段惯性滑动但必须配合动画循环里的controls.update()。忘记这一步是惯性控制不生效的最常见原因。3.2 r137 材质发灰时先检查 outputEncoding上面的代码跑起来后很多同事的第一个反馈是蓝色材质比设计稿暗一截。这不是显示设备的问题而是 r137 默认没有做 sRGB 输出转换。修复方法是在 renderer 创建后加两行renderer.outputEncoding THREE.sRGBEncoding;如果用了外部的 albedo 贴图还需要对贴图单独标记const texture new THREE.TextureLoader().load(texture.png); texture.encoding THREE.sRGBEncoding;这个 API 在 r137 里是有效的但到了 r150 以后outputEncoding被outputColorSpace替代枚举也从THREE.sRGBEncoding变成THREE.SRGBColorSpace。如果你在搜three.js新版代码时直接复制outputColorSpace到 r137 里会得到 undefined。反之把旧代码sRGBEncoding粘到新版工程里也会失效。这是 r137 和现代版本之间最常见的兼容地雷放到后面第 5 章的检查清单里专门验证。4. r137 离线包接入数字孪生工程examples/jsm 的加载路径与依赖方式three.js-r137.zip最有价值的地方在于它完整保留了examples/jsm目录在离线环境里可以直接引用OrbitControls、GLTFLoader等官方扩展。这在工业数字孪生项目中非常常见系统部署在隔离内网不能在线拉取 CDN也没有 npm 私有仓库一个 zip 包就是唯一的依赖来源。4.1 importmap 与 examples/jsm 的依赖关系examples/jsm下的模块分散在controls/、loaders/、objects/等子目录里模块之间常用相对路径互相引用也会引用three这个 bare import。比如 r137 的OrbitControls.js顶部可能是import { ... } from three;。如果你在自己的工程里直接 import 这个文件但页面没有定义 importmap浏览器无法把three解析成一个 URL会报 “Failed to resolve module specifier”。所以在使用 zip 包内的任何 jsm 扩展前必须先在入口 HTML 里定义统一的 importmap{ imports: { three: ./build/three.module.js } }这样examples/jsm/controls/OrbitControls.js内部的import ... from three才能命中同一个three.module.js。注意这里的three映射一定要指向模块版本而不是three.min.js因为 min 版本不是 ES Module无法被 import 语法复用。4.2 不放心时先查模块内部 import 了谁拿到陌生 zip 包时我习惯先查一下它的真实依赖而不是猜。进入解压目录后执行cd three.js-r137 grep -Rho from .* examples/jsm | sed s/from // | sort -u这段命令把examples/jsm下所有 ES Module 引用的来源粗略列出来。输出里如果出现from three说明依赖顶层 importmap如果出现from ./xxx.js或from ../xxx.js说明它依赖 zip 包内的相对文件。看到路径后用ls对照一下对应文件是否存在就能在编码前排除缺失依赖的问题。如果拿到的是一个从 GitHub 页面直接下载的源码 zip有时examples/jsm里的依赖会指向../../examples/fonts这类资源目录。只要整个 zip 都在相对路径不会断真正容易断的是你把jsm某个文件单独复制到项目里却没有带上它引用的兄弟文件。4.3 在 r137 里加载一个 GLB 模型下面是接入模型加载的最小片段。这里我假设你已经把模型放在站点根目录的models/下。import * as THREE from three; import { GLTFLoader } from ./examples/jsm/loaders/GLTFLoader.js; import { OrbitControls } from ./examples/jsm/controls/OrbitControls.js; const container document.querySelector(#app); const renderer new THREE.WebGLRenderer({ antialias: true, alpha: true }); renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); renderer.setSize(container.clientWidth, container.clientHeight); container.appendChild(renderer.domElement); const scene new THREE.Scene(); const camera new THREE.PerspectiveCamera( 45, container.clientWidth / container.clientHeight, 0.1, 2000 ); camera.position.set(10, 8, 10); const controls new OrbitControls(camera, renderer.domElement); controls.enableDamping true; scene.add(new THREE.AmbientLight(0xffffff, 0.8)); const dirLight new THREE.DirectionalLight(0xffffff, 1.5); dirLight.position.set(5, 10, 7); scene.add(dirLight); const loader new GLTFLoader(); loader.load( ./models/room.glb, (gltf) { scene.add(gltf.scene); const box new THREE.Box3().setFromObject(gltf.scene); const center box.getCenter(new THREE.Vector3()); controls.target.copy(center); }, undefined, (err) console.error(GLTF 加载失败, err) ); function animate() { requestAnimationFrame(animate); controls.update(); renderer.render(scene, camera); } animate();代码里renderer增加了alpha: true这样页面背景能透明方便和cesium等底图合成的工业数字孪生页面做叠加。GLTFLoader的load回调里用Box3计算模型包围盒再把相机控制目标移动到模型中心避免模型偏在原点外看不全。GLTF 加载失败分支里最常见的错误是本地模型路径 404或者纹理文件路径对不上先看 Network 面板别急着改代码。4.4 三种获取 three.js 的方式怎么选把前面的选型汇总成一张表对带离线限制的项目尤其有用来源版本锁定离线可用工程化便利度注意点CDN 引入URL 中版本号否低内网不可用版本不可控npm 安装package-lock需要镜像缓存高升级时副作用大zip importmap物理文件是中需要自行管理静态服务路径在 r137 这个版本下alpha: true的透明背景页面往往是最先被用到的集成点。要注意WebGLRenderer的alpha打开后如果还用scene.background设置不透明颜色透明效果会被覆盖。常见做法是让页面背景由外层 DOM/Cesium 决定three.js 场景里不设置 background。5. 拿到 three.js-r137.zip 后先做三次检查版本、依赖与颜色空间最后用一个 10 分钟能做完的检查流程收住这个主题。每次拿到陌生 zip 包或在 r137 工程里排查问题时我按顺序做下面三件事。5.1 验证 REVISION 而不是目录名package.json和文件夹名都可以被改但运行时版本号不会骗人。在页面控制台执行import * as THREE from three; console.log(THREE.REVISION);输出137就说明页面加载的就是 r137。如果输出了别的数字说明你虽然拿着 r137 的 zip但实际项目引用了另一个构建文件。反过来如果项目已经混入了新版本THREE.REVISION会立刻暴露问题。5.2 用 grep 列出扩展模块的依赖路径从 GitHub 下载的 zip 包大多数是完整的但手动拷贝examples/jsm下的单个文件时很容易漏掉兄弟文件。在解压后的根目录执行cd three.js-r137 grep -Rho from .* examples/jsm | sed s/from // | sort -u如果输出里只有three和../、./开头的路径你可以按路径逐个确认。所有相对路径的目标都要存在于 zip 包内否则浏览器会在运行时 404。这个命令不关注from three因为那是 importmap 的职责范围。5.3 颜色空间回归新老 API 的判断r137 代码里用renderer.outputEncoding THREE.sRGBEncoding;是合法写法。但在代码里做一次防御性判断可以避免未来迁移时炸掉if (THREE.ColorManagement ! undefined) { renderer.outputColorSpace THREE.SRGBColorSpace; } else { renderer.outputEncoding THREE.sRGBEncoding; }这个判断依据是THREE.ColorManagement是否存在r150 有它r137 没有。这样同一份页面在 r137 和现代版本下都能得到正确的 sRGB 输出。把这段逻辑放到渲染器初始化末尾再配合THREE.REVISION的检查r137 包是否真的生效、扩展模块是否完整、颜色是否走对三件事就都验证完了。本文还有配套的精品资源点击获取
