TextureLoader 加载失败却无报错，主因是 CORS 限制或路径错误，需启动本地服务、检查 Network 请求状态；贴图赋值后须设 material.needsUpdate = true；重复显示需设置 texture.wrapS/T 和 repeat。
TextureLoader 加载失败但控制台没报错？检查 CORS 和路径
Three.js 的 TextureLoader 本质是用 Image 对象加载图片，不走 fetch，所以跨域失败时往往静默失败（onError 不触发，纹理黑/灰），尤其本地直接双击 HTML 打开时，file:// 协议下所有图片加载都会被浏览器拦截。必须启动一个本地服务（如 python3 -m http.server 或 VS Code Live Server）。
路径也容易出错：相对路径以 HTML 文件所在目录为基准，不是 JS 文件位置。比如 index.html 在项目根目录，js/app.js 里写 loader.load('textures/rock.jpg')，实际找的是 ./textures/rock.jpg，不是 ./js/textures/rock.jpg。
- 用浏览器开发者工具 Network 标签页确认图片请求状态码是否为 200
- 在
loader.load()第二个参数（onProgress）里加console.log('loading...')，确认是否进入回调 - 临时改用绝对路径（如
/assets/wood.jpg）排除相对路径歧义
贴图加载后材质没更新？别忘了设置 needsUpdate
贴图加载是异步的，而材质创建通常在加载前就完成了。常见错误是把 texture 赋给 material.map 后，没告诉 Three.js 这个材质变了——尤其是复用已有材质时。
正确做法是在 loader.load() 的完成回调里显式设置：
立即学习“前端免费学习笔记（深入）”；
基于三引擎设计，从微信文章、新闻和博客网页提取干净内容，支持标题作者日期元数据，多格式和批量处理。
const loader = new THREE.TextureLoader();
loader.load('brick.jpg', (texture) => {
material.map = texture;
material.needsUpdate = true; // 关键！
});
注意：needsUpdate = true 只需设一次，且仅对已添加到场景中的材质生效；如果材质还没被使用（比如还没 add 到 mesh），可以先赋值再添加，不用立即设 needsUpdate。
- 若材质用了多张贴图（
normalMap、roughnessMap），每张都要单独加载并分别设needsUpdate = true -
MeshStandardMaterial等 PBR 材质对贴图格式敏感，确保roughnessMap是灰度图，normalMap是 OpenGL 风格（Y 向上）
为什么贴图拉伸或重复异常？检查 wrapS / wrapT 和 repeat
默认情况下，Three.js 的 Texture 对象的 wrapS 和 wrapT 是 THREE.ClampToEdgeWrapping，也就是边缘截断，不会平铺。如果你希望砖墙纹理重复，得手动改：
loader.load('brick.jpg', (texture) => {
texture.wrapS = texture.wrapT = THREE.RepeatWrapping;
texture.repeat.set(2, 2); // U 方向重复 2 次，V 方向重复 2 次
material.map = texture;
material.needsUpdate = true;
});
注意：repeat 是 Vector2，不是数字；repeat.set(1, 1) 表示原始大小不缩放，set(4, 2) 表示横向铺 4 份、纵向铺 2 份。
- 修改
repeat或offset后，同样需要texture.needsUpdate = true（但多数情况可省略，Three.js 内部会处理） - 如果模型 UV 坐标超出 [0,1] 范围，且
wrap是ClampToEdgeWrapping，超出部分会显示为边缘像素，看起来像“拉伸”
用 Canvas 动态生成贴图？TextureLoader 不适用，改用 Texture 构造
TextureLoader 只处理 URL 加载，无法加载 HTMLCanvasElement 或 ImageData。想运行时画点东西当贴图（比如实时仪表盘、粒子印记），得绕过 Loader：
const canvas = document.createElement('canvas');
const ctx = canvas.getContext('2d');
canvas.width = 256; canvas.height = 256;
ctx.fillStyle = 'red'; ctx.fillRect(0, 0, 256, 256);
// 创建纹理对象
const texture = new THREE.Texture(canvas);
texture.needsUpdate = true; // 必须！否则黑屏
material.map = texture;
这种手动构造的 Texture，后续修改 canvas 内容后，每次都要再调 texture.needsUpdate = true 才能刷新画面。
- 避免在动画循环（
requestAnimationFrame）里频繁重绘大尺寸 canvas，性能损耗明显 - 如果只是改颜色或简单图形，考虑用
ShaderMaterial+ uniform 控制，比 canvas 更高效
