企业官网建设流程全解析

简介：面向Web前端与3D开发人员的three.js压缩版多版本合集，涵盖r64至r87共二十余个常用版本。three.js作为浏览器端应用最广泛的3D图形库，不同项目常因插件兼容、API接口差异或渲染性能要求而锁定特定版本，这份集合免去逐一查找下载的麻烦，按项目实际需求选取对应three.min.rXX.js文件即可直接引用。压缩包共22个JS文件均为.min.js格式，整体约2.29MB，体积轻量，适合作为本地开发资源库。已有2677人学习下载。版本跨度从r64到r87，覆盖了three.js快速演进的重要阶段，期间包含性能优化、新特性引入、API重构与错误修复等多方面改进，开发者既可按需取用稳定版本，也可对照查看不同版本核心方法与模块的差异，对系统理解three.js的发展脉络、排查版本兼容性问题均有实际帮助。

1. 为什么要手工维护一份 three.min.js 多版本集合

接手一个跨了三个年头的 WebGL 项目时，你大概率会遇到同一个尴尬：老页面跑在 r128 上，新需求却要用 r150 才有的 API，直接升级一把梭，结果纹理加载、射线拾取、动画回放全链路翻车，光回归测试就耗掉一周。这时候才意识到，与其每次靠改 package.json 赌版本兼容，不如在本地维护一份 three.min.js 多版本集合，随用随切，出问题十分钟内回滚。

所谓多版本集合，就是把不同发布周期的 Three.js 压缩构建文件按目录、按规则统一收纳，配套加载与切换手段，让同一个站点里不同模块能各自锁定版本。它解决的不是“最新版有多强”，而是“旧项目还能不能安全活着”这件事。适合三类人：维护老项目的业务开发、做 Web 3D 工具链的工程效率党、以及被客户指定“不许动现有版本”的交付团队。

这份集合的落地路径很清晰：先搞懂构建文件背后的版本差异，再搭目录、收文件、做校验，接着解决加载与切换，最后把常见兼容性坑位钉死在排查清单里。下面按这条线一步步拆开讲。

2. 弄懂 three.min.js 的前世今生：构建产物与版本选型逻辑

2.1 压缩文件里的三样东西：核心、模块与扩展

拿到任何一个 three.min.js，里面实际打包的只有核心渲染管线、场景图管理与基础数学库，像 OrbitControls、GLTFLoader、CSS3DRenderer 这类扩展能力从来不在压缩文件里，需要单独引 “examples/js” 或 “examples/jsm” 下的对应文件。很多人直接把多版本集合理解成“多存几个压缩文件”，动手时才发现每个版本还拖着一堆 addons，版本切换时 addons 与核心不匹配才是最大的坑。

核心与扩展的对应关系在不同版本间变化很大。早期版本（r120 之前）习惯用全局 THREE 命名空间，扩展文件通过 THREE.OrbitControls 挂载；r120 之后官方强推 ES Module，扩展文件变成import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js'。这意味着你收集的每个 three.min.js 版本，必须连同它同时期的扩展文件一起收，否则切了版本后控制器和加载器直接罢工。

构建产物的体积也能反映版本差异。r128 的 three.min.js 大约 600 KB（未 gzip），到 r150 已经涨到 700 KB 以上，核心原因是新增了光照贴图、物理渲染、动画系统内部重构。如果你的项目对首屏体积敏感，多版本集合里放“够用的旧版本”往往比追逐新版更划算。

注意：多版本集合不是把文件堆在一起就完事，核心、扩展、样式（如 CSS2DRenderer 的样式）、类型声明四类文件要按版本成套归档。

2.2 版本号里的规律：r 前缀、向后兼容与破坏性变更

Three.js 的版本号一直用 r 加数字，比如 r128、r150，每个大版本之间不承诺完全兼容。实践中可以把版本分成三类：稳定期版本（r120~r140，API 变化少，适合老项目）、过渡期版本（r141~r152，开始强推模块化，全局 THREE 逐步弱化）、新架构版本（r153+，渲染器内部改动大，WebGPU 相关功能陆续进入）。选型时先看项目里用了哪些 API，再去版本里确认这些 API 是否还在。

典型破坏性变更清单值得收藏：r139 移除了THREE.Geometry，所有基于 BufferGeometry 的旧写法必须重写；r143 改了光照探针的 API；r147 把outputEncoding改成了outputColorSpace；r152 开始默认使用 color space 管理。你要是从老版本直升新版，光这几个变更就能让材质颜色、阴影效果全部大变样。

版本选定后还有个容易忽略的点：同一版本号下存在 UMD 与 ESM 两套构建。three.min.js 属于 UMD 构建，直接 script 标签引用后暴露全局 THREE；而three.module.js是 ESM 构建，供 import 使用。做多版本集合时，我一般 UMD 和 ESM 各留一份，UMD 应对快速实验和老页面，ESM 应对新模块化工程。

2.3 从哪收集文件：CDN、npm 包与本地构建三选一

收集版本文件有两个可靠途径。第一是 npm 包：执行npm pack three@0.128.0会得到一个 tgz 压缩包，解压后build目录里就是对应版本的 three.min.js 与 three.module.js，扩展文件在examples/jsm下，这种做法最干净，文件完整且版本绝对对应。第二是官方 CDN，通过固定版本号的路径直接下载，但 CDN 上部分历史版本的目录结构做过调整，下载时要留意路径变化。

我习惯用 npm 包方式，好处是版本与源码、扩展文件、类型声明完全绑定，不会出现“核心是 r150、扩展是 r128”的混搭事故。缺点是需要 Node 环境，但做前端工程的人基本都有。收到 tgz 后，先解压到临时目录，确认build/three.min.js存在再进集合目录。

# 用 npm pack 拉取指定版本的完整发布包 mkdir -p /tmp/three-collect && cd /tmp/three-collect npm pack three@0.128.0 # 得到 three-0.128.0.tgz，解压后检查目录结构 tar -tzf three-0.128.0.tgz | head -20

这段命令的意义是先确认包内容再落地，避免把不完整的文件放进集合。head -20只是快速瞄一眼目录，完整解压用tar -xzf即可。npm pack 与 npm install 的区别在于前者只下载发布包到本地，不会写入 node_modules，更适合做文件收集。

参数说明：three@0.128.0中的版本号必须与目标版本完全一致，npm 支持three@0.128这样的模糊匹配，但既然要做版本集合，建议写精确版本；-tzf是“列出 tar 包内文件列表”的组合参数，z表示 gzip 解压，t表示列表，f表示指定文件。

3. 从零搭一套 three.min.js 本地版本集合：目录、文件与校验

3.1 目录规划：一套能扛住三个年头的结构

目录结构直接决定切换版本时的心智负担。常见做法是按“版本号/构建类型/文件”三层组织，每个版本目录里只放这个版本自己的核心与扩展，绝不跨版本共享文件。下面这套结构我沿用了很久，项目从 r128 一路切到 r152 都没乱过。

three-versions/ ├── r128/ │ ├── three.min.js │ ├── three.module.js │ ├── types/ │ └── addons/ │ ├── OrbitControls.js │ ├── GLTFLoader.js │ └── CSS2DRenderer.js ├── r139/ │ ├── three.min.js │ ├── three.module.js │ ├── types/ │ └── addons/ ├── r150/ │ ├── three.min.js │ ├── three.module.js │ └── addons/ └── versions.json

versions.json是这个集合的索引文件，记录每个版本的引入路径、依赖项和已知变更，相当于给每个版本做个档案。有了它，切换版本时不用去源码里翻 API 差异，直接查档案就能预判风险。

{ "r128": { "entry": "r128/three.min.js", "umd": true, "module": "r128/three.module.js", "addons": { "OrbitControls": "r128/addons/OrbitControls.js", "GLTFLoader": "r128/addons/GLTFLoader.js" }, "breakingChanges": [] }, "r150": { "entry": "r150/three.min.js", "umd": true, "module": "r150/three.module.js", "addons": { "OrbitControls": "r150/addons/OrbitControls.js", "GLTFLoader": "r150/addons/GLTFLoader.js" }, "breakingChanges": ["outputEncoding -> outputColorSpace"] } }

这段 JSON 的价值在于让“切换”从玄学变成可查证的操作：接入某个版本前先看breakingChanges，有相关条目就直接在代码里做适配。umd和module两个布尔字段是提醒自己该版本是否同时具备两套构建，避免后来者误以为只有一种引用方式。

3.2 批量收集脚本：一条命令补齐五个版本

手工逐个 npm pack 太慢，写一个收集脚本放进集合目录里，以后补版本只需执行一次。脚本的核心逻辑是遍历版本列表、逐个 pack、解压、归类、清理。这里给出一个可直接改用的 bash 脚本，重点在与 npm 交互和文件搬移的细节。

#!/usr/bin/env bash # three-versions/collect.sh set -euo pipefail VERSIONS=( "0.128.0" "0.139.0" "0.150.0" ) TMP_DIR=$(mktemp -d) TARGET_DIR=$(dirname "$0") for v in "${VERSIONS[@]}"; do echo "collecting three@$v ..." npm pack "three@$v" >/dev/null 2>&1 PKG_FILE="three-$v.tgz" mkdir -p "$TMP_DIR/$v" tar -xzf "$PKG_FILE" -C "$TMP_DIR/$v" # package/ 是解压后的固定顶层目录 BUILD_DIR="$TMP_DIR/$v/package/build" EXAMPLES_DIR="$TMP_DIR/$v/package/examples/jsm" mkdir -p "$TARGET_DIR/r$v/addons" cp "$BUILD_DIR/three.min.js" "$TARGET_DIR/r$v/three.min.js" [ -f "$BUILD_DIR/three.module.js" ] && cp "$BUILD_DIR/three.module.js" "$TARGET_DIR/r$v/three.module.js" # 只复制常用 addons，避免文件过杂 cp "$EXAMPLES_DIR/controls/OrbitControls.js" "$TARGET_DIR/r$v/addons/" 2>/dev/null || true cp "$EXAMPLES_DIR/loaders/GLTFLoader.js" "$TARGET_DIR/r$v/addons/" 2>/dev/null || true rm "$PKG_FILE" done rm -rf "$TMP_DIR" echo "done."

脚本逻辑按“版本循环→pack→解压→归类”展开。set -euo pipefail确保任一步失败即终止，不产生半成品目录。mktemp -d生成临时目录存放解压内容，脚本结束统一清理，不会把临时文件遗留在集合里。2>/dev/null || true表示某个 addon 在旧版本里不存在时直接跳过，不影响其他文件收集。

参数说明：版本列表按需自行增减；cp目标目录用r$v拼接，版本号 0.150.0 会被自动映射为 r150 目录；只有three.module.js存在时才复制，早期版本可能只有 UMD 构建。如果某版本没有某个 addon，|| true保证脚本继续执行，后续可以在 versions.json 里手动标注缺失项。

3.3 文件校验三板斧：体积、哈希与可用性

文件收集完了，别急着用，先过三关校验。第一关看体积：three.min.js 的正常体积在 600~750 KB 之间，如果只有几十 KB，大概率是下载到了错误页面或网络中断。第二关算哈希：每个版本记录一个 SHA-256，之后文件损坏、被误改都能立刻发现。第三关是加载冒烟：用一个最小 HTML 页面引进去，确认THREE.REVISION与目录名一致。

# 对每个版本目录计算哈希，输出到 versions.sha256 sha256sum three-versions/r*/three.min.js > three-versions/versions.sha256 # 之后任何时候校验集合完整性 cd three-versions && sha256sum -c versions.sha256

哈希校验是集合维护的后悔药：哪天发现某个页面渲染异常，先跑一遍完整性检查，排除文件被篡改的可能再查代码。sha256sum -c会逐行比对哈希，输出OK或FAILED，FAILED 行就是需要重新收集的文件。

<!-- 冒烟测试页面：只检查版本号是否正常暴露 --> <!DOCTYPE html> <html> <head><meta charset="utf-8"></head> <body> <script src="../r150/three.min.js"></script> <script> console.log('THREE.REVISION =', THREE.REVISION); if (!THREE.WebGLRenderer) throw new Error('r150 未正确加载'); const renderer = new THREE.WebGLRenderer({ antialias: true }); document.body.appendChild(renderer.domElement); renderer.setSize(300, 150); </script> </body> </html>

这段冒烟脚本做了两件事：打印THREE.REVISION确认版本号，然后实例化一个 WebGLRenderer 确认渲染器能创建成功。antialias: true只是测试参数，实际项目按需调整。如果控制台报THREE is not defined，说明文件路径错误或引入顺序不对；如果WebGLRenderer构造成功但页面黑屏，先检查 WebGL 上下文是否被浏览器禁用。

4. 让多个版本在同一页面里和平共处：加载、隔离与切换

4.1 script 标签直引：最快跑通，但要小心版本串扰

如果整个页面只用某一个版本，script 标签直引最简单。但多版本集合的价值就在于“同一站点不同页面用不同版本”，直引时注意别把两个版本的 three.min.js 同时放进同一个页面，全局THREE对象会被后加载的版本覆盖，先加载的版本直接失效，所有功能瞬间变成新版本行为。

实践中常见做法是根据页面路由动态决定引哪个版本，而不是物理上放两个 script 标签。比如管理后台用 r128，前台展示用 r150，每个页面模板只引入自己那个版本。

<!-- 按页面路由动态选择版本 --> <script> // 页面级别决定版本号，写入 data 属性，再由加载器执行 window.PAGE_THREE_VERSION = 'r150'; </script> <script> (function () { var version = window.PAGE_THREE_VERSION || 'r128'; var script = document.createElement('script'); script.src = '../../three-versions/' + version + '/three.min.js'; script.onload = function () { console.log('当前 THREE.REVISION =', THREE.REVISION); }; document.head.appendChild(script); })(); </script>

这段动态加载脚本把版本号与页面配置解耦：新增页面时只用改PAGE_THREE_VERSION，不用动加载逻辑。script.onload里打印版本号是做确认，实际项目中可替换为初始化 3D 场景的入口函数。注意脚本加载是异步的，后续初始化代码必须放进onload回调，否则可能在 three.min.js 还没就绪时就去访问THREE。

4.2 命名空间隔离：两个版本同页共存的终极方案

有时候确实存在同页两个模块各用各的版本：比如一个数据可视化组件锁死 r128，另一个新功能模块指定 r150。此时全局 THREE 冲突无法回避，唯一稳的做法是构建隔离：

<!-- 隔离加载器：把不同版本挂到不同容器对象上 --> <script> window.__THREE_BUNDLES__ = {}; function loadThreeVersion(version, callback) { if (window.__THREE_BUNDLES__[version]) { callback(window.__THREE_BUNDLES__[version]); return; } var script = document.createElement('script'); script.src = '../../three-versions/' + version + '/three.min.js'; script.onload = function () { // 把当前全局 THREE 暂存到版本容器，再把全局还原成旧值 var current = window.THREE; window.__THREE_BUNDLES__[version] = current; callback(current); }; document.head.appendChild(script); } // 模块 A 用 r128，模块 B 用 r150 loadThreeVersion('r128', function (THREE_A) { new THREE_A.Scene(); }); loadThreeVersion('r150', function (THREE_B) { new THREE_B.WebGLRenderer(); }); </script>

注意这段代码有一个隐藏问题：第二个版本加载时，会把第一个版本残留的全局 THREE 覆盖掉，但第一个版本已经被暂存在__THREE_BUNDLES__容器里，后续通过容器取用而不是直接用全局。实际项目中两个版本加载体量的同时还要注意内存：加载两个完整的 three.min.js 会让首屏体积翻倍，尽量只在后台管理类页面使用这种隔离，对体积敏感的公网页面慎用。

4.3 打包工具里的多版本：import 路径映射与别名

在 Webpack、Vite 这类工程里，多版本集合的用法不是动态 script，而是通过别名切换。常见做法是在配置里为不同版本设置别名，代码里按需 import。这种方法的好处是享受 tree-shaking 和模块缓存，坏处是同一时间只能有一个版本生效，做不到同页共存。

// vite.config.js 中为多版本设置别名 import { defineConfig } from 'vite'; export default defineConfig({ resolve: { alias: { // 业务模块里 import * as THREE from 'three' 会走到 r128 'three': '/src/three-versions/r128/three.module.js', // 特殊模块可以显式用 'three-r150' 走新版 'three-r150': '/src/three-versions/r150/three.module.js', } } });

配置里的关键是“默认别名保持稳定，特殊模块用限定别名”。three指向 r128，意味着大多数老代码不用改；three-r150是新增的显式别名，只有明确需要新 API 的模块才引用它。迁移时可以渐进式改造：老模块继续走默认，新模块用新版，等老模块逐步重写完成，再把默认别名整体切到新版。

参数说明：import * as THREE from 'three'的写法要求 three.module.js 内部导出结构固定，如果某版本模块结构有变化，需要统一在各模块入口封装一层再导出。

5. 多版本集合的 5 个高频坑：现象、原因与排除方法

5.1 切了版本后材质颜色整体变亮

现象：同一段代码，从 r128 切到 r150 后，模型颜色明显过曝或偏色，材质像是丢了颜色管理。

原因：r152 起 Three.js 默认启用了新的颜色管理机制，线性工作流成为默认，而老代码里 605 的MeshPhongMaterial颜色值仍按 sRGB 语义写入，导致渲染结果差异。

解决：切到新版时，在初始化阶段显式设置颜色空间，让旧数据按旧逻辑解释。代码里在创建渲染器后加入renderer.outputColorSpace = THREE.SRGBColorSpace，同时确认纹理的colorSpace赋值正确。

const renderer = new THREE.WebGLRenderer(); // 切版本后的第一行，先锁定颜色行为再往下写业务 renderer.outputColorSpace = THREE.SRGBColorSpace; // 对旧纹理，显式声明颜色空间，避免两次转换 texture.colorSpace = THREE.SRGBColorSpace;

这段代码的关键在于“让新旧版本的渲染结果先对齐，再响应业务需求”。如果注释掉outputColorSpace赋值，新版默认会走线性输出，颜色偏亮。纹理侧不声明colorSpace，旧纹理可能被当成线性纹理处理，整体变灰。

5.2 addons 与核心版本混搭，加载器直接报错

现象：OrbitControls 引入正常，但调用new OrbitControls(camera, renderer.domElement)时提示THREE.OrbitControls is not a constructor，或者 GLTFLoader 找不到THREE.Loader。

原因：r120 之前的 addons 依赖全局 THREE 命名空间，r120 之后的 addons 用 ES Module 导出。混搭指的是核心用 r128 的 three.min.js，addons 却从 r150 的 jsm 目录复制，两边内部引用不一致，构造函数挂载失败。

解决：严格按版本配套使用 addons。每次收集版本时，从同一版本的examples/jsm下复制 addons，绝不跨版本复制。遇到老项目正在用旧版，但旧版 addons 文件丢失时，优先重新拉取对应版本，而不是拿新版凑合。

5.3 阴影效果在新版里大量消失或边缘闪烁

现象：从 r139 切到 r150 后，场景里原本正常的阴影变得稀疏、闪烁，甚至大面积消失。

原因：r140 之后阴影渲染的默认配置发生了变化，shadow.mapSize的默认值不再自动适配，同时部分LightShadow参数语义调整，旧代码里的数值解释不同。

解决：切换版本时把阴影参数显式写全，不依赖默认值：

const light = new THREE.DirectionalLight(0xffffff, 1); light.castShadow = true; // 显式设置阴影贴图尺寸，避免默认值变化导致闪烁 light.shadow.mapSize.set(2048, 2048); // 阴影相机范围按场景实际尺寸收紧，减少边缘伪影 light.shadow.camera.near = 0.5; light.shadow.camera.far = 100; light.shadow.camera.left = -10; light.shadow.camera.right = 10; light.shadow.camera.top = 10; light.shadow.camera.bottom = -10;

mapSize.set(2048, 2048)是治阴影模糊和闪烁的常用手段，数值越大阴影越精细但性能开销越高，具体按场景调。camera系列参数决定了阴影相机的视锥范围，范围过大反而会让贴图精度被浪费，范围过小阴影会被裁切。切版本后先看这两个值有没有因为默认值变化而偏移，再排查其他材质问题。

5.4 打包后体积暴涨，多版本文件全被打进产物

现象：用 Vite 或 Webpack 打包时，发现three相关的 chunk 体积异常，明明只用了 r150，r128 和 r139 的文件也出现在产物里。

原因：代码里存在对多个版本的显式 import，或者别名配置把某目录整个引进来，导致打包器把多个 three 构建全部视为依赖收入产物。

解决：排查代码中是否残留three-r128、three-r139等显式引用；如果项目只需要一个版本，直接删除多余别名；需要多版本共存时就接受体积翻倍，但可把不同版本拆分到不同路由的异步 chunk 里，避免首屏一次加载全部版本。

5.5 切换版本后 GLTFLoader 行为不一致，模型加载偶尔卡住

现象：模型在 r128 下加载稳定，切到 r150 后偶发超时或解析失败，尤其是一些老工具导出的 glTF 2.0 文件。

原因：新版本 GLTFLoader 对 glTF 数据的校验更严格，某些历史导出文件存在的轻微数据不严格问题会被解析器捕捉并抛错。

解决：先确认模型本身能通过 glTF Validator 校验；不能改模型文件时，考虑在加载器层面做容错处理，或者暂时保留旧版本处理存量模型。实际项目里我会把加载器包一层，内部统一捕获解析异常并降级到旧版本加载器处理，这样新老模型都能平稳加载。

6. 把多版本集合做成团队基建：从文件堆到版本中心

管理多版本集合最怕的就是“收了一堆文件，没人记得哪个版本对应哪段业务”。我的做法是把集合升级成一个简易版本中心：用一份索引文件（versions.json）记录每个版本的引入路径、已用业务模块、已知破坏性变更，同时统一封装一个加载器把版本与 addons 绑定。这样团队成员不关心物理文件，只按业务需要声明版本号，由封装层去完成加载与校验。

版本中心的加载器核心是登记与分发。登记是指每个版本首次接入时，在索引里记录谁在用、用了哪些特性；分发是指加载器根据请求返回对应版本的 THREE 实例及 addons，保证调用方拿到的版本与请求一致。这一步做完后，新增业务模块时不用再问“我们项目现在用的是哪个版本”，看一眼索引即可。

一个长期维护的版本中心，还要养成两个习惯。第一，每次收新版本时顺带跑一遍冒烟例程，把渲染、加载、交互三个最小场景都过一遍，结果记录进索引，避免“文件在但不可用”的假性库存。第二，至少每个季度做一次版本普查，统计哪些版本还有实际调用、哪些已经没人用，老版本保留几份做备份即可，不需要无限堆积，否则版本中心退化成硬盘里的文件坟场。

切换版本前，我会固定做一次三问检查：当前代码用到的 API 在新版本里是否还在、行为语义是否有变化、addons 是否配套。这套检查用掉的时间通常不超过二十分钟，但能挡掉大部分切版本翻车事故。多版本集合真正值钱的地方就在这里，它不是让你去追新，而是让你在追新或者保旧时都能从容落地，希望帮到你。

本文还有配套的精品资源，点击获取