Three.js 的项目做多了你会发现真正决定画面“高级感”的往往不是模型精细度而是纹理材质这一层。同样一个盒子贴上贴图和没贴贴图是两回事同样一张贴图采样参数、色彩空间、UV处理方式不一样观感差距能拉到天上去。这几年我在实际项目里反复调过纹理加载、PBR 贴图、动态纹理、显存回收这些环节踩过的坑不少但摸清规律之后它们的表现非常稳定。这篇文章就把我在 Three.js 纹理材质高级操作上验证过的经验完整梳理一遍。无论是刚接触 Three.js 想快速跑通一个带贴图的示例还是已经在做比较复杂的材质系统应该都能直接用上。先说一个很多人纠结的问题Three.js 怎么下载、怎么快速创建项目。新版本早就走 ES Module 路线了没必要再下载整个 build 文件塞进 script 标签。直接用 npm 装一个 three配合 Vite 搭一个最简工程几分钟就能看到第一个带纹理的立方体。后面的所有坑都从这一步开始谈。1. 环境与基础加载先把纹理这条路走通1.1 三分钟跑通第一个带贴图的场景快速创建项目这件事网上教程很多但真正干净利落的流程其实是固定的。装依赖、创建入口文件、写一个最小场景三步就够了npm init -y npm install three npm install -D vite然后在项目里建一个 main.jsimport * as THREE from three; const scene new THREE.Scene(); const camera new THREE.PerspectiveCamera(45, innerWidth / innerHeight, 0.1, 100); camera.position.set(3, 3, 3); camera.lookAt(0, 0, 0); const renderer new THREE.WebGLRenderer({ antialias: true }); renderer.setSize(innerWidth, innerHeight); document.body.appendChild(renderer.domElement); const geometry new THREE.BoxGeometry(1, 1, 1); const texture new THREE.TextureLoader().load(/textures/box.png); const material new THREE.MeshStandardMaterial({ map: texture }); scene.add(new THREE.Mesh(geometry, material)); renderer.render(scene, camera);切换到项目目录执行npx vite打开浏览器看到贴图立方体基础链路就算通了。这里强调一个容易被新手忽略的点纹理路径是相对于页面根目录的而不是相对于 JS 文件所以/textures/box.png和./textures/box.png在 Vite 开发环境里的解析规则不一样放错位置最常见的结果就是控制台报 404而不是报 Three.js 本身的错误。1.2 跨域问题贴图加载失败的另一半原因纹理加载失败很多人第一时间怀疑路径但还有一种情况更隐蔽图片资源放在 CDN 或另一台静态服务器上跨域读取时没带 CORS 头纹理对象创建成功了画面却是黑的控制台还会冒出一句The image element contains cross-origin data...。这并不是 Three.js 的 bug。WebGL 纹理上传要求图片资源允许跨域读取所以需要给图片元素加上crossOrigin anonymous。如果资源在你自己控制的服务上务必让后端在响应头里返回Access-Control-Allow-Origin。我在项目里就被这个坑过一次排查了半天最后发现是 CDN 配置少了一行跨域头。用 TextureLoader 加载时它内部已经帮图片设置了crossOrigin但如果你是手动创建HTMLImageElement再传给纹理一定要自己设置const img new Image(); img.crossOrigin anonymous; img.src https://cdn.example.com/textures/wood.jpg; const texture new THREE.Texture(img); texture.needsUpdate true;2. 纹理加载的进阶姿势从单张到一套资产2.1 LoadingManager多纹理加载必须做进度管理单张贴图的加载根本不需要进度条但项目里会有几十上百张贴图时没有加载管理器用户盯着白屏完全不知道还要等多久。Three.js 提供的 LoadingManager 就是干这个的。const manager new THREE.LoadingManager(); manager.onProgress (url, loaded, total) { console.log(已加载 ${loaded} / ${total}${url}); }; manager.onLoad () { console.log(全部贴图加载完成); }; const textureLoader new THREE.TextureLoader(manager);它会帮你聚合所有纹理加载的进度加载完成后再去创建材质、渲染场景这才是正经项目该有的节奏。而且 LoadingManager 可以复用到 GLTFLoader、KTX2Loader 等所有加载器上一套进度体系统一管所有资源。如果不用 LoadingManager最常见的失误是贴图还没加载完材质已经创建好并渲染了结果画面上出现一个不发光的灰色模型。Three.js 纹理加载是异步的纹理对象在一开始就有了但图像数据可能还没到位texture.image还是空的。可以先渲染等加载完再触发一次渲染也可以干脆先不创建材质。2.2 纹理命名规范和文件预处理到了这个阶段纹理就不该再叫abc.png、final(1).jpg了。贴图资产必须有一套明确的命名规则我自己的习惯是用后缀区分用途box_color.jpg基础颜色贴图box_normal.png法线贴图box_roughness.jpg粗糙度贴图box_metalness.jpg金属度贴图box_ao.jpg环境光遮蔽贴图box_emissive.jpg自发光贴图命名清晰的好处不止是方便查找。后期如果要做程序化打包、批量处理、压缩格式转换完全可以靠后缀写脚本批量操作不用人工去逐个分辨。文件预处理也有讲究。能转 WebP 的地方尽量转 WebP体积小、画质不错。需要透明通道的贴图保留 PNG不需要透明通道的压缩图尽量导成 JPG 或 WebP。别拿一张 2K 的砖墙贴图直接扔进场景先在 Photoshop 或者在线工具里缩到实际需要的尺寸再交给 Three.js能省很多显存。2.3 纹理缓存的坑loader 的 cache 默认是开着的TextureLoader 内部自带缓存同一个 URL 第二次加载不会重复发请求而是直接返回第一次的纹理对象。这个行为大多数时候是好的但如果你做的是编辑器类工具用户替换纹理后又重新加载同一个 URL拿到的还是旧纹理会让人非常困惑。解决方法是调用TextureLoader().cache.clear()或者换个带时间戳的 URL比如texture.png?t1699999999强制绕开缓存。这种问题在长期运行的 Web 应用里经常遇到属于典型的“平时用不到用到就要命”的知识点。3. 纹理采样与 UV贴图糊、花、拉伸的三个元凶3.1 wrapS/wrapTUV 超出 [0,1] 后怎么办贴图渲染异常很大一部分原因出在采样参数上。Three.js 纹理有wrapS和wrapT两个属性分别控制 U 方向横向和 V 方向纵向超出纹理坐标范围后的行为。可选项有三种ClampToEdgeWrapping默认UV 超过 1 就钳制到 1取边缘像素。适合不需要重复的贴图。RepeatWrapping贴图平铺重复做地板、墙面、布料这种周期性纹理必用。MirroredRepeatWrapping镜像重复接缝处不会有肉眼可见的硬切边适合做对称图案。一个非常经典的场景是木地板。你拿到一张地板贴图希望在一个大平面上重复 4 次但直接设置texture.repeat.set(4, 4)之后如果还是默认的 Clamp结果就是整块地板被拉伸花得不能看。正确的做法是const texture new THREE.TextureLoader().load(/textures/floor.jpg); texture.wrapS THREE.RepeatWrapping; texture.wrapT THREE.RepeatWrapping; texture.repeat.set(4, 4);注意修改了wrapS、wrapT、repeat这些属性后大多数时候需要执行一次texture.needsUpdate true否则 WebGL 侧用的还是旧纹理状态。尤其在一个纹理对象创建后过一段时间再去改这些参数漏掉这一步非常容易出问题。3.2 minFilter、magFilter 和 mipmap 的作用纹理放大和缩小时的采样策略由magFilter和minFilter控制这俩看着不起眼实际影响非常大。当一个像素覆盖的贴图像素面积小于一个纹素时纹理被放大了用LinearFilter做双线性插值画面会平滑。而当贴图被缩小一个像素覆盖多个纹素时如果还直接采样远处就会出现高频闪烁和明显的摩尔纹动画时尤其明显这就是典型的“远处画面在闪”。解决缩小采样的问题靠的是 mipmap。可以这样理解mipmap 就是给纹理提前准备了多级“缩略图”从 1/2 尺寸、1/4 尺寸一直往小排。远处采样时直接取对应层级的小图而不是对着原图硬缩质量立刻提升。Three.js 里默认的minFilter是LinearMipmapLinearFilter也就是三线性过滤只要纹理允许生成 mipmap它就会自动处理。但在有些动态纹理场景里比如 Canvas 纹理每帧都在更新mipmap 的重新生成会带来额外开销。如果不需要 mipmap可以把minFilter改成LinearFilter同时texture.generateMipmaps false性能会好不少代价是缩放质量差一点。这属于典型的功能换取性能的取舍。3.3 anisotropy一个参数解决斜视角糊成一片物体贴着屏幕时纹理是清晰的但你蹲下来斜着看地面远处的地砖纹理越来越糊即使 mipmap 开了也救不回来。这其实是各向异性过滤没用上。这个参数控制的是“当视角倾斜时采样区域沿某个方向拉长系统是否主动去更合适的 mipmap 层级采样”。默认值 1 意味着完全不启用各向异性地面斜着看就退化得很厉害设成 8 或 16清晰度会有质的提升。texture.anisotropy renderer.capabilities.getMaxAnisotropy();大多数项目直接取显卡支持的最大值就行性能开销可以接受。但要记住一个前提如果minFilter设置的是NearestFilter即没有启用任何 mipmap 链anisotropy 能发挥的作用就非常有限几乎没效果因为底层采样逻辑根本不依赖 mipmap。4. PBR 贴图体系只贴一张彩色图是不合格的4.1 标准材质的贴图组合很多初学者习惯性认为“贴图 颜色图”给模型贴上一张map就完事了。但如果用的是MeshStandardMaterial或MeshPhysicalMaterial只给map的话材质本质上还是一个很“塑胶感”的东西。原因很简单真实世界里的材质颜色只是表面信息的一部分。砖墙在灯光下的凹凸感要靠法线贴图模拟金属的反光强度和锐利度由金属度、粗糙度共同决定环境光遮蔽图则决定了缝隙和角落的暗部深度。这些通道都是独立的。一套标准的 PBR 贴图流程长这样const textureLoader new THREE.TextureLoader(); const material new THREE.MeshStandardMaterial({ map: textureLoader.load(/textures/wall_color.jpg), normalMap: textureLoader.load(/textures/wall_normal.png), roughnessMap: textureLoader.load(/textures/wall_roughness.jpg), aoMap: textureLoader.load(/textures/wall_ao.jpg), });如果你用的模型是 GLTF 格式GLTFLoader 会自动把它的 PBR 贴图解析进材质不需要手动逐个指定。但如果是手动拼材质一定要注意这几张贴图的尺寸和 UV 保持一致一旦某张贴图尺寸不同或者平铺次数不一致就会出现“颜色有砖缝法线却是平的或者说颜色图有重复法线图没有对应重复”的诡异画面。这个我踩过不止一次手动指定时尽量全部统一用同一套 UV 坐标和 repeat 设置。4.2 法线贴图为什么在部分网格上失效法线贴图本身是切线空间的偏移量数据。材质系统采样法线贴图前需要知道网格的切线方向将切线空间的法线转换到世界空间。Three.js 的 GLTF 模型会自动处理切线数据但如果是手工构建的 BufferGeometry很多情况下并没有真正的切线数据。一个常见问题是网格旋转、缩放后法线贴图效果明显不对或者说模型某些区域高光位置乱飘。这就是切线数据缺失或归一化处理不彻底导致的。最直接的排查方法是输出几何体的 tangent 属性console.log(geometry.attributes.tangent);如果是 undefined或者值是 NaN就需要自己重新计算geometry.computeTangents();另外BufferGeometry默认使用非索引三角形列表computeTangents 可以直接跑。但如果模型有镜像 UV、重叠 UV 这种“不干净”的 UV 布局生成的切线会在接缝处产生明显的硬裂痕法线贴图效果就会跳变。这种情况光靠 computeTangents 救不回需要在建模软件里重新分 UV。所以法线贴图问题的根源很多不在 Three.js 代码里而在模型资产的 UV 质量上。4.3 置换贴图是最贵的那个别盲目用如果说法线贴图是用“假凹凸”骗眼睛置换贴图就是真实移动顶点。Three.js 的displacementMap会根据贴图的明暗值沿法线方向把顶点顶出去。它的优势是轮廓真的变了影子也是对的但代价极高。一个平面默认的PlaneGeometry只有 1x1 个分段4 个顶点。给这种平面加displacementMap无论贴图多精细顶点根本不够用完全没效果。想看到真实的位移效果必须提高几何体分段数const geometry new THREE.PlaneGeometry(2, 2, 128, 128); const material new THREE.MeshStandardMaterial({ map: textureLoader.load(/textures/terrain_color.jpg), displacementMap: textureLoader.load(/textures/terrain_height.png), displacementScale: 0.2, });128x128 分段意味着 16512 个顶点这还是实验性的规模。如果模型本身已经几十万顶点再加上置换贴图的重算帧率基本扛不住。所以实际项目里我的优先级是能用法线贴图就不上置换贴图必须要真实轮廓时优先考虑“低模 置换 法线”的组合而不是直接上高模返工成本会低很多。5. 动态纹理与资源生命周期5.1 VideoTexture把视频画面贴在模型上视频纹理是动态纹理的代表用法非常直接创建一个 video 元素交给VideoTexture即可。const video document.createElement(video); video.src /videos/lcd.mp4; video.muted true; video.loop true; video.play(); const texture new THREE.VideoTexture(video); texture.colorSpace THREE.SRGBColorSpace; const material new THREE.MeshStandardMaterial({ map: texture });移动端有几个绕不开的坑。iOS 上视频必须通过用户触摸事件触发播放单纯video.play()会被拦截另外很多浏览器要求视频静音才能自动播放所以项目里通常会做一个“点击屏幕后开始播放”的交互。视频纹理默认每次渲染前都会检查视频画面是否更新如果视频暂停或播放完毕画面会一直停留在最后一帧。如果视频画面发灰或者偏色最典型的处理是把texture.colorSpace设置成THREE.SRGBColorSpace。视频数据本质上也是 sRGB 编码的颜色信息不告诉 Three.js 这一点后续显示就会出错。以前很多老教程里用encoding属性r152 版本之后已经改名成colorSpace写新代码时不要再照搬旧写法。5.2 Canvas 纹理动态数据可视化的利器把 Canvas 作为纹理可以做出很多动态效果比如雷达扫描、仪表盘表针、实时图表。核心逻辑就是把 Canvas 画好然后作为纹理传入材质const canvas document.createElement(canvas); canvas.width 512; canvas.height 512; const ctx canvas.getContext(2d); const texture new THREE.CanvasTexture(canvas); texture.colorSpace THREE.SRGBColorSpace; // 每帧更新 Canvas 内容后 texture.needsUpdate true;这里有一个老生常谈但每次都有人踩的点Canvas 的坐标原点在左上角但 WebGL 纹理默认的flipY是 true等于说 Canvas 内容会被垂直翻转。如果你在 Canvas 上画文字贴到模型上会发现文字上下颠倒。解决办法是手动设置texture.flipY false但要注意改了 flipY 后纹理的 V 方向坐标会跟着变采样时心里要有数。5.3 WebGLRenderTarget把渲染结果当纹理用比 Canvas 纹理更“Three.js 原生”的动态纹理来源是WebGLRenderTarget。它的原理是离屏渲染先把场景渲染到一张“虚拟画布”上再把这个画布的内容作为普通纹理贴到另一个材质里。最常见的用途是后处理和镜面反射。比如我要做一个实时监控画面的屏幕可以先单独创建一个 render target把监控摄像机渲染进去再把它的 texture 贴到室内的显示屏模型上const rt new THREE.WebGLRenderTarget(1024, 1024); const screenTexture rt.texture; // 渲染流程 renderer.setRenderTarget(rt); renderer.render(monitorScene, monitorCamera); renderer.setRenderTarget(null); renderer.render(mainScene, mainCamera);这里有个关键纪律不能一边往 render target 里写一边又在同一帧里读它作为纹理去渲染主场景顺序必须是“先写后读”。并且如果 render target 关联的纹理要参与主场景渲染主场景材质采样它的时机必须在这一帧离屏渲染完成之后。这个顺序问题我见过很多人搞反导致画面闪烁或者全是黑色。5.4 管理纹理内存不会 dispose 的项目离不开内存崩溃WebGL 纹理是存在 GPU 显存里的JavaScript 的垃圾回收管不到它。如果你不断创建新纹理、替换旧纹理而不手动释放几十分钟后显存就会被占满浏览器标签页直接白屏甚至崩溃。Three.js 里对应的方法是texture.dispose()。当纹理确定不再使用后调用它GPU 资源才会被释放。带纹理的材质同样需要material.dispose()几何体也要geometry.dispose()。很多时候三个是一起释放的我习惯封装一个disposeObject方法递归遍历场景树把 mesh、material、texture 和 geometry 统一回收。另一个常见的资源浪费是重复加载。一个场景里有几十个 Mesh 但共用同一张贴图有些人图省事每个 Mesh 都单独 new 一个 TextureLoader 去加载同一张图结果 GPU 里存了十几份一模一样的纹理。正确做法是做一个纹理缓存池加载过的纹理保存下来后面所有 Mesh 共享同一个 texture 实例。6. 色彩空间与纹理优化6.1 颜色发灰发暗先查色彩空间“渲染出来颜色总是灰蒙蒙的”“暗部死黑一片”——这种问题十有八九是色彩空间设置错误。简单说屏幕上的图片是经过 gamma 预编码的 sRGB 值而 Three.js 渲染光照时需要在线性空间里计算亮度。如果你把一个 sRGB 贴图直接当成线性数据去参与光照计算中间调的颜色会被错误地压暗画面自然灰、闷、不通透。Three.js 的处理方式是靠texture.colorSpace告诉引擎这张图的数据是 sRGB 编码的采样时要先解码成线性值光照计算完后再统一编码回 sRGB 显示。const texture new THREE.TextureLoader().load(/textures/color.jpg); texture.colorSpace THREE.SRGBColorSpace;这里有一个极其重要的区分只有“颜色贴图”需要设置成SRGBColorSpace法线贴图、粗糙度贴图、金属度贴图、AO 贴图、高度贴图这些本质上都是数据不是颜色全部保持默认的线性空间千万不能设置成 sRGB。如果把法线贴图误设成 sRGB法线数据会被扭曲光照结果直接乱掉高光位置错得离谱。从 r152 版本开始renderer.outputColorSpace默认已经是SRGBColorSpace渲染输出的颜色空间基本不用管重点就是记住贴图侧的 colorSpace 设置。还有一点加载 GLTF 模型时GLTFLoader 会自动处理 model 内部纹理的 colorSpace通常是 sRGB 颜色贴图才设为 SRGB但材质里的其他数据贴图不会乱标。手动处理模型时反而要留心这一点不要重复设置。6.2 纹理压缩与显存预算一张图让你看清成本纹理分辨率不是越大越好因为显存是实打实的。RGB 通道的贴图在 GPU 上每像素占 3 字节RGBA 占 4 字节。一张 2048x2048 的 RGBA 贴图就是 2048x2048x4 16MB。听着还能接受但如果场景里 30 张贴图就是 480MB已经非常危险了。要命的是还有 mipmap完整 mip 链会额外增加大约三分之一的显存占用一张 2K RGBA 纹理的实际显存开销接近 21MB。所以纹理压缩不是“优化手段”而是大中型场景的必需品。Three.js 支持 KTX2 格式配合KTX2Loader和 Basis Universal 转码器可以把贴图压缩成 GPU 直接支持的硬件压缩格式比如桌面端的 BC7、移动端的 ASTC。使用流程稍微有点复杂要先生成.ktx2文件再在 Three.js 里注册加载器去读取但它带来的显存降幅非常明显同样是 2048x2048 的贴图压缩后可能降到原来的四分之一甚至更低。如果你的项目主要跑在普通桌面浏览器上也可以考虑用 WebP 或 AVIF 这类通用图片格式虽然它们不是 GPU 硬件解压但至少在传输体积上能大幅缩减。真正决定 GPU 显存占用的还是纹理在 WebGL 中上传时的原始格式所以压缩纹理对大项目是绕不开的。6.3 needsUpdate 使用纪律别把 GPU 提交变成性能灾难最后说一个性能纪律级别的细节texture.needsUpdate true的含义是“这个纹理的 GPU 数据需要重新上传/重新生成 mipmap”。它是必须设置的但设置得太奢侈性能就会崩。有一种非常典型的错误写法在动画循环里给一个 Canvas 纹理每帧都执行needsUpdate true哪怕 Canvas 内容根本没有变化。后果就是 GPU 每帧都在重新上传纹理数据、重新生成 mipmap帧率立刻往下掉。正确的做法是只有在纹理数据真正发生变化时才设置一次。比如 Canvas 更新完内容后设一次视频纹理则不需要手动设VideoTexture 内部会根据视频帧状态自动管理。还一个细节是批量修改纹理属性时wrap、filter、colorSpace、flipY 一起改needsUpdate只需要设一次不需要每个属性改完都设一次。7. 常见问题排查速查表在实际调试里纹理相关的问题大多数现象都很相似但原因千差万别。我把这几年遇到的典型问题整理成一个速查表排查时可以先按这个顺序过一遍。问题现象可能原因解决方案贴图加载后模型仍是灰色纹理尚未加载完成就创建材质并渲染使用 LoadingManager 等待全部加载再渲染控制台报 CORS 错误且画面黑跨域资源未设置 CORS 头后端配置 Access-Control-Allow-Origin贴图上下颠倒Canvas 纹理与 flipY 设置冲突按需设置 texture.flipY false远处纹理闪烁模糊mipmap 或 anisotropy 设置不当确认 minFilter 默认为 LinearMipmapLinearFilter适当提高 anisotropy地面砖缝被拉伸wrapS/wrapT 还是默认 ClampToEdge设置 RepeatWrapping 并同时设置 repeat改完纹理参数没变化忘记设置 needsUpdate统一修改后执行一次 needsUpdate true法线贴图高光乱跳网格缺少切线或 UV 质量差geometry.computeTangents()或回建模软件修 UV模型颜色发灰发暗颜色贴图 colorSpace 没设为 SRGBtexture.colorSpace THREE.SRGBColorSpace视频纹理偏色或灰色视频颜色空间未声明设置 SRGBColorSpace贴图替换后显存持续增长旧纹理没有 dispose不用时调用 texture.dispose()并释放材质和几何体屏幕贴图黑色一片离屏渲染顺序错误先写 render target再读它渲染主场景纹理文件一换就失效TextureLoader 缓存未清理清理 loader cache 或加时间戳参数排查这些问题的顺序也有讲究。先看控制台有没有 404 和 CORS 报错这是最基础、也最容易排除的一层。然后再看纹理的 colorSpace再看 wrap 和 filter最后才深入法线切线、UV 布局那种资产侧的问题。别一上来就怀疑模型资产先在自己代码层把可能性清零效率会高得多。做纹理材质调试的时候我习惯开一个临时场景只放一个立方体和一个平面把要用的贴图分别贴上去配合简单的 DirectionalLight 直接看效果。等确认贴图本身和采样参数没问题再拿去接主场景的材质。这种“隔离调试”的方式能极大减少变量之间的干扰很多问题几分钟就能定位。还有一个小技巧是所有 PBR 贴图统一加载后写一个小工具函数做校验检查每个纹理的image.width、image.height、colorSpace和anisotropy集中打日志。把所有纹理的状态一次性拉出来看比在代码里翻一个个对象找问题要直观得多。这个习惯帮我省过不少时间也推荐你试试。
