8.2 生态工位：扩展库、WebXR 与社区

8.2 生态工位：扩展库、WebXR 与社区

本节摘要：产线不必一切自研。本节盘点官方示例模块库的存货（前文用过的控制器、加载器、后期器原来都住在这里），走通 WebXR 的最小出货流程，并给出社区资源的检索姿势——遇到问题的查找顺序比任何单个答案都值钱。

半个标准件仓库就在官方仓库里

回看全册用过的"非本体"部件：OrbitControls（第 4 章）、GLTFLoader 与 DRACOLoader（第 5 章）、EffectComposer 全家（第 7 章）。它们不是第三方库，全部住在 Three.js 官方仓库的示例模块目录里——官方把"常用但不必进核心"的部件都放在这个半成品仓库。盘点一遍存货，很多"我要找个库"的念头会当场打消：各类相机控制器（轨道、飞行、第一人称）、几十种格式加载器、后期效果器全家桶、程序化几何与曲线辅助、字体与骨骼工具。引法统一走模块导入，前文的每一处 import 都是同一套姿势。

判断"功能该找生态还是自研"有一条粗线：通用且工程量大的（控制器、格式解析）先查官方示例库；业务专属的（你的货架逻辑、货箱信息卡）必然自研；介于两者之间的，先查官方示例库有没有"可改的毛坯"——多数毛坯改十几行就能进自己的产线。

WebXR：第 1 章预留的出货口

第 1 章工装底座里选 setAnimationLoop 而不是手写 requestAnimationFrame，理由此刻兑现：WebXR 模式下渲染节奏由头显设备驱动，手写循环会错拍，setAnimationLoop 会自动切换。Three.js 把 XR 支持做成了渲染器的开关属性，最小出货流程只有五步：启用 XR 开关、声明沉浸模式、把按钮挂上页面、（可选）在循环里读控制器姿态、按住"不破坏平面版"的原则写代码——XR 打开时同一份场景直接进头显。

// 最小 XR 出货：五步走完
stage.renderer.xr.enabled = true;                        // 1 开关
navigator.xr?.isSessionSupported('immersive-vr').then((ok) => {
  if (!ok) return;                                       // 设备不支持就静默跳过
  import('three/addons/webxr/VRButton.js').then(({ VRButton }) => {
    document.body.appendChild(VRButton.createButton(stage.renderer)); // 2 加 3
  });
});
// 4 与 5：底座的 setAnimationLoop 已就绪；XR 会话中控制器姿态可经
// renderer.xr.getController(0) 读取，平面版代码一行不改
​

结果：支持的设备上页面多出一枚"进入 VR"按钮，点击后同一沙盘以立体视差呈现；不支持的设备与普通页面毫无区别。这个"渐进增强"结构是 XR 出货的标准姿势——XR 是增量特性，不是平行版本。

动手：建立自己的检索动线

背景：新需求"沙盘水面要能反光流动"。要求：按高效动线找方案，不重复造轮子，也不病急乱投库。

操作：四层动线，从内到外。

// 第一层：官方示例库检索——关键词 Water
// 命中示例模块 water 与 ocean，都是可改毛坯：前者轻量平面波，
// 后者大型海面。沙盘场景选前者，改十几行参数即可入库
import { Water } from 'three/addons/objects/Water.js';
const water = new Water(planeGeo, {
  textureWidth: 512,
  textureHeight: 512,
  waterNormals: waterNormalsTex,   // 法线贴图负责波纹观感
  sunDirection: sun.position.clone().normalize(),
  sunColor: 0xffffff,
  distortionScale: 2.4             // 波动幅度：仓库地面积水要克制
});

// 第二层：文档与示例站对照——确认参数含义与兼容版本
// 第三层：社区问答——精确描述现象再检索，带上版本号
// 第四层：源码直读——示例模块都是几百行的可读代码，读源码是终极答案
​

结果：水面半天上线，代码量不到百行，参数全部可控。若走错动线（先去搜第三方"3D 水库"），大概率引入一个数 MB 的全家桶，只为一个平面波——生态用错地方，负资产。

解读：动线的排序逻辑值得说透：第一层官方示例库，因为它的部件与本体版本天然同步、质量有底线；第二层文档，确认参数语义与版本兼容——Three.js 的破坏性升级不少，旧答案可能害人；第三层社区问答，关键词要"现象 + 版本"而不是"报错贴全文"；第四层直读源码，示例模块体量小、注释全，读源码比翻十篇二手教程更快也更准。四层动线之外有一条红线：引入任何第三方库前先看它是否只是官方能力的重复实现——生态的目的是站在标准件上，不是站在更多家供应商的谈判桌上。

变式：社区里值得长期关注的还有官方的版本更新日志（破坏性变更第一时间知道）与各开源画廊项目的"查看源码"入口——画廊页面就是活的作业本。团队协作场景下，把常用扩展模块的引法与版本固定进工装底座（1.2），新人开箱即用。

版本纪律：生态借力的保险丝

借力生态有一条不可省的保险丝：版本纪律。Three.js 的破坏性升级在历史上不算温和——光照单位改制、色彩空间默认值变更，都曾让旧代码的画面一夜变样。落地为三条纪律：其一，锁定具体版本号而非浮动符号，升级是主动决策不是被动发生；其二，升级前读官方的迁移说明，重点看渲染器默认值一节；其三，工装底座（1.2）里固定全部扩展模块与本体的版本配对，新人拉下来的环境与线上分毫不差。另一条容易被忽视的纪律是"示例代码的时效性"：网上的教程片段自带写作时的版本烙印，跑不通先查版本差，再怀疑自己的写法——多数"网上代码都跑不通"的挫败，答案只是差了两个大版本。

本节要点回顾

• 官方示例库是半个仓库：控制器、加载器、后期器都在里面，import 姿势全册统一；
• 生态找毛坯：通用件先查官方，业务件必自研，中间态改毛坯；
• XR 是开关不是分身：enabled 开关加 VR 按钮，平面版代码零改动；
• 四层检索动线：示例库、文档、社区、源码，从内到外逐层升级；
• 带版本问问题：破坏性升级频繁，一切检索都要钉住版本号。

生态已收编。最后一节交货：把全册工序放进一场真实交付里复盘——项目流程、三类订单的装配差异、上线后的售后。