【ThreeJs】【自帶依賴】Three.js 自帶依賴指南

🛠? Three.js 輔助庫生態手冊

定位：覆蓋 90% 開發場景的工具選型+實操指南，區分「入門必備」和「進階擴展」。
適用人群：Three.js 新手（≥ r132 版本）、需要規范開發流程的團隊。

1. 控制器（Controls）：讓用戶“摸得到”3D場景

📌 核心作用

通過鼠標、鍵盤、觸控實現相機交互，是 3D 場景的“基礎交互入口”。
場景舉例：產品3D展示（旋轉查看）、FPS游戲（第一人稱移動）、漫游系統（飛行瀏覽）。

🔍 工具選型表（按使用頻率排序）

優先級	控制器名稱	核心功能	適用場景	自帶/引入方式
???	OrbitControls	軌道旋轉+縮放+平移，帶邊界限制	產品3D展示、模型查看	需引入：`import { OrbitControls } from 'three/addons/controls/OrbitControls.js';`
??	FirstPersonControls	第一人稱視角（WASD移動+鼠標轉向）	FPS游戲、虛擬漫游	需引入：`import { FirstPersonControls } from 'three/addons/controls/FirstPersonControls.js';`
??	FlyControls	自由飛行（類似飛船操控）	大場景漫游（如數字城市）	需引入：`import { FlyControls } from 'three/addons/controls/FlyControls.js';`
?	PointerLockControls	鎖定鼠標（隱藏指針，純視角控制）	沉浸式游戲、VR交互前置	需引入：`import { PointerLockControls } from 'three/addons/controls/PointerLockControls.js';`

?? 入門實操：OrbitControls 基礎用法

效果：鼠標左鍵旋轉、右鍵平移、滾輪縮放，限制相機最小/最大距離。

// 1. 引入并實例化（依賴 camera 和 renderer.domElement）
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';const controls = new OrbitControls(camera, renderer.domElement);// 2. 核心配置（必調參數）
controls.enableDamping = true; // 開啟阻尼（平滑交互）
controls.dampingFactor = 0.05; // 阻尼系數（越小越平滑）
controls.minDistance = 5; // 相機最近距離
controls.maxDistance = 50; // 相機最遠距離
controls.maxPolarAngle = Math.PI / 2; // 禁止俯視到地平面以下// 3. 動畫循環中更新（否則阻尼不生效）
function animate() {requestAnimationFrame(animate);controls.update(); // 關鍵：更新控制器狀態renderer.render(scene, camera);
}
animate();

?? 避坑提示

OrbitControls 默認會禁用相機的 position.z 手動修改，如需同時控制，需設置 controls.screenSpacePanning = false;。
FirstPersonControls 需單獨處理鍵盤事件，建議搭配 KeyboardState 庫監聽按鍵。

2. 加載器（Loaders）：導入外部3D資源

📌 核心作用

將設計師輸出的 模型（GLB/FBX）、紋理（JPG/PNG/KTX2）、動畫 轉化為 Three.js 可識別的對象。
行業主流：GLB 格式（體積小、支持動畫/材質，優先選擇）；KTX2 紋理（壓縮率高，適合移動端）。

🔍 工具選型表（按資源類型分類）

資源類型	加載器名稱	支持格式	核心優勢	自帶/引入方式
紋理	TextureLoader	JPG/PNG/WEBP	基礎紋理加載，核心庫自帶	自帶：`new THREE.TextureLoader().load('texture.jpg');`
紋理	KTX2Loader	.ktx2	GPU 紋理壓縮，節省內存	需引入：`import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';`
模型	GLTFLoader	.gltf / .glb	支持動畫、PBR材質、壓縮	需引入：`import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';`
模型	FBXLoader	.fbx	兼容老版3DMax輸出模型	需引入：`import { FBXLoader } from 'three/addons/loaders/FBXLoader.js';`
模型壓縮	DRACOLoader	配合 GLTFLoader	減小 GLB 模型體積（50%+）	需引入：`import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';`

?? 進階實操：GLTFLoader + DRACOLoader 加載壓縮模型

場景：加載 10MB+ 的 GLB 模型，用 DRACO 壓縮后體積降至 3MB 左右。

// 1. 引入加載器
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';// 2. 配置 DRACO 解碼器（需下載解碼器文件到本地）
const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('libs/draco/'); // 解碼器路徑（從 three/examples/jsm/libs/draco 復制）
dracoLoader.setDecoderConfig({ type: 'js' });// 3. 關聯 GLTFLoader 并加載模型
const gltfLoader = new GLTFLoader();
gltfLoader.setDRACOLoader(dracoLoader); // 啟用 DRACO 解壓縮gltfLoader.load('models/product.glb', // 模型路徑(gltf) => { // 加載成功回調scene.add(gltf.scene); // 將模型添加到場景console.log('模型加載成功：', gltf);// 如需播放動畫：gltf.animations 存放動畫數據},(xhr) => { // 加載進度回調console.log(`加載中：${(xhr.loaded / xhr.total) * 100}%`);},(error) => { // 加載失敗回調console.error('模型加載失敗：', error);}
);

📎 資源準備

DRACO 解碼器下載：Three.js 官方 examples/libs/draco
模型壓縮工具：Blender 導出 GLB 時勾選“DRACO Compression”。

3. 調試輔助（Helpers）：可視化“看不見”的元素

📌 核心作用

開發階段顯示 坐標軸、相機視錐、光源位置、物體邊界 等不可見元素，快速定位問題（如“模型為什么看不見？因為在相機視錐外”）。
發布建議：上線前刪除所有 Helper 代碼，避免性能消耗。

🔍 常用 Helper 速查表

Helper 名稱	功能說明	自帶/引入	基礎用法示例
AxesHelper	顯示 X(紅)/Y(綠)/Z(藍) 坐標軸	自帶	`scene.add(new THREE.AxesHelper(5));` // 5 為坐標軸長度
GridHelper	顯示網格地面（輔助定位物體）	自帶	`scene.add(new THREE.GridHelper(20, 20, 0xcccccc, 0x999999));` // 大小/細分/顏色
CameraHelper	顯示相機的視錐體（ frustrum ）	自帶	`const camHelper = new THREE.CameraHelper(camera); scene.add(camHelper);`
PointLightHelper	顯示點光源的位置和照射范圍	自帶	`const lightHelper = new THREE.PointLightHelper(pointLight, 1); scene.add(lightHelper);`
Box3Helper	顯示物體的包圍盒（碰撞檢測前置）	自帶	`const boxHelper = new THREE.Box3Helper(mesh.geometry.boundingBox); scene.add(boxHelper);`

📸 效果示意圖（文字描述替代圖片）

AxesHelper：場景中心出現紅、綠、藍三根軸，紅色指向右（X軸），綠色指向上（Y軸），藍色指向屏幕外（Z軸）。
CameraHelper：以線框形式顯示相機的“視野范圍”，如果模型在框外，則說明相機看不到該模型。

4. 后期處理（Postprocessing）：讓畫面“更高級”

📌 核心作用

渲染完成后對畫面進行二次加工，實現 抗鋸齒、泛光、描邊、景深 等特效，提升視覺質感。
核心邏輯：EffectComposer（容器）+ 多個 Pass（特效通道）疊加。

🔍 常用特效表（按效果分類）

特效類型	模塊名稱	效果說明	引入方式
基礎容器	EffectComposer	后期處理的核心容器（必用）	`import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';`
抗鋸齒	FXAAPass	快速抗鋸齒（適合性能有限場景）	`import { FXAAPass } from 'three/addons/postprocessing/FXAAPass.js';`
泛光	UnrealBloomPass	模擬 unreal 引擎的泛光效果	`import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';`
描邊	OutlinePass	高亮物體邊緣（選中效果常用）	`import { OutlinePass } from 'three/addons/postprocessing/OutlinePass.js';`
環境光遮蔽	SSAOPass	增強物體陰影細節（更真實）	`import { SSAOPass } from 'three/addons/postprocessing/SSAOPass.js';`

?? 實操示例：抗鋸齒 + 泛光效果

// 1. 引入模塊
import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
import { FXAAPass } from 'three/addons/postprocessing/FXAAPass.js';
import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';// 2. 初始化后期容器
const composer = new EffectComposer(renderer);// 3. 添加基礎渲染通道（必須第一個）
const renderPass = new RenderPass(scene, camera);
composer.addPass(renderPass);// 4. 添加抗鋸齒通道
const fxaaPass = new FXAAPass();
composer.addPass(fxaaPass);// 5. 添加泛光通道
const bloomPass = new UnrealBloomPass(new THREE.Vector2(window.innerWidth, window.innerHeight), // 窗口大小1.5, // 泛光強度0.4, // 泛光半徑0.85 // 閾值（亮度超過該值才會泛光）
);
composer.addPass(bloomPass);// 6. 動畫循環中替換 renderer.render 為 composer.render
function animate() {requestAnimationFrame(animate);controls.update();composer.render(); // 用后期容器渲染，而非直接用 renderer
}
animate();

? 性能提示

后期處理會增加 GPU 負擔，移動端建議只保留 FXAAPass，避免泛光/SSAO。
多個 Pass 疊加時，按“基礎渲染 → 效果處理 → 輸出”的順序添加。

📋 開發規范建議（團隊級）

1. 目錄結構（按功能分層）

src/
├── three/
│   ├── controls/    # 控制器實例（如 OrbitControls.js）
│   ├── loaders/     # 加載器封裝（如 modelLoader.js）
│   ├── post/        # 后期處理配置（如 bloomEffect.js）
│   └── helpers/     # 調試輔助（開發時引入，上線時刪除）