three-base 2.0.196 → 2.0.198

package/pass/stroke_pass.js

@@ -38,12 +38,6 @@ const selectDepthTestTextureTarget = new WebGLRenderTarget(1024, 1024, {
 });
 const blur1TextureTarget = new WebGLRenderTarget(1024, 1024, { minFilter: LinearFilter, magFilter: LinearFilter, format: RGBAFormat });
 const blur2TextureTarget = new WebGLRenderTarget(1024, 1024, { minFilter: LinearFilter, magFilter: LinearFilter, format: RGBAFormat });
-// 外扩深度临时/结果目标：depthMinBlurShader 把本体深度图随描边一起外扩，
-// 外扩区取邻域最近深度（忽略背景 1.0），使外扩区 selD<1.0，depthTest 才能正确判遮挡（不漏光）。
-const selectDepthBlurTmpTextureTarget = new WebGLRenderTarget(1024, 1024, { minFilter: LinearFilter, magFilter: LinearFilter, format: RGBAFormat });
-const selectDepthBlurTextureTarget = new WebGLRenderTarget(1024, 1024, { minFilter: LinearFilter, magFilter: LinearFilter, format: RGBAFormat });
-// 外扩描边经深度测试后的结果（步骤 5.6）：独立 target，避免回写 blur1 触发历史回归 bug
-const blurDepthTestTextureTarget = new WebGLRenderTarget(1024, 1024, { minFilter: LinearFilter, magFilter: LinearFilter, format: RGBAFormat });
 const size = new Vector2();
 const depthTestShader = new ShaderMaterial({
     uniforms: {
@@ -383,52 +377,6 @@ const strokeShader = new RawShaderMaterial({
     depthWrite: false,
     transparent: true
 });
-// 深度 min-blur（最近深度，忽略背景 1.0）：随描边一起把深度图向外扩，
-// 外扩区 selD = 物体最近深度(<1.0) 而非清屏 1.0，depthTest 在外扩区才能正确判遮挡（不漏光），
-// 同时本体区仍靠 depthTestShader 的 EPSILON 容差防自遮挡闪烁（无缝）。separable（direction 控制 H/V）。
-const depthMinBlurShader = new ShaderMaterial({
-    uniforms: {
-        tDepth: { value: null },
-        resolution: { value: new Vector2(1 / 512, 1 / 512) },
-        radius: { value: 1.0 },
-        direction: { value: new Vector2(1, 0) },
-    },
-    vertexShader: `
-        ${ShaderChunk.common}
-        ${ShaderChunk.logdepthbuf_pars_vertex}
-        varying vec2 vUv;
-        void main() {
-            vUv = uv;
-            gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
-            ${ShaderChunk.logdepthbuf_vertex}
-        }
-    `,
-    fragmentShader: `
-        ${ShaderChunk.logdepthbuf_pars_fragment}
-        uniform sampler2D tDepth;
-        uniform vec2 resolution;
-        uniform float radius;
-        uniform vec2 direction;
-        varying vec2 vUv;
-        void main() {
-            float minD = 1.0;
-            for (int i = -10; i <= 10; i++) {
-                float x = float(i);
-                vec2 off = direction * (x * radius * resolution);
-                float d = texture2D(tDepth, vUv + off).r;
-                if (d < 0.9999) {
-                    minD = min(minD, d);
-                }
-            }
-            gl_FragColor = vec4(minD, 0.0, 0.0, 1.0);
-            ${ShaderChunk.logdepthbuf_fragment}
-        }
-    `,
-    blending: NoBlending,
-    depthTest: false,
-    depthWrite: false,
-    transparent: true,
-});
 const filterSelectShader = new RawShaderMaterial({
     uniforms: {
         selectTexture: { value: null },
@@ -508,9 +456,6 @@ export default function stroke_pass(renderer, camera, object3d, baseDepthTexture
     selectDepthTestTextureTarget.setSize(size.x, size.y);
     blur1TextureTarget.setSize(size.x, size.y);
     blur2TextureTarget.setSize(size.x, size.y);
-    selectDepthBlurTmpTextureTarget.setSize(size.x, size.y);
-    selectDepthBlurTextureTarget.setSize(size.x, size.y);
-    blurDepthTestTextureTarget.setSize(size.x, size.y);
     // 1. 渲染物体本体 mask（灰度）。⭐ 本体深度由同一趟光栅化顺带写进 selectDepthTexture
     //   （挂在 selectTextureTarget 的 depth attachment 上）—— 原先这里还有第 2 趟「只渲深度」，
     //   同材质/同相机/同几何 ⇒ 深度逐位相同，纯重复遍历，2026-10-11 皇上旨简化时删除。
@@ -532,7 +477,8 @@ export default function stroke_pass(renderer, camera, object3d, baseDepthTexture
     depthTestShader.uniforms.cameraFar.value = camera.far;
     depthTestShader.uniforms.uDebugVis.value = (window.__STROKE_DEPTH_VIS) ? 1.0 : 0.0;
     fsQuad.render(renderer, depthTestShader);
-    // 4. 从「深度测试后的本体描边」开始外扩（外扩环自动继承本体遮挡判定 → 不漏光），
+    // 4. 从「深度测试后的本体描边」开始外扩（外扩的源头是本体判过的结果，被挡掉的本体不会再长出描边；
+    //    但外扩出来那圈像素本身不再判深度 ⇒ 贴着遮挡物时会压到遮挡物前面，见步骤 6 的代价点名），
     //    描边粗细由 stroke_width 控制的迭代次数决定。
     strokeShader.uniforms.resolution.value.set(1 / size.x, 1 / size.y);
     FXAAShaderMaterial.uniforms.resolution.value.set(1 / size.x, 1 / size.y);
@@ -557,42 +503,14 @@ export default function stroke_pass(renderer, camera, object3d, baseDepthTexture
     renderer.setRenderTarget(blur1TextureTarget);
     FXAAShaderMaterial.uniforms.tDiffuse.value = blur2TextureTarget.texture;
     fsQuad.render(renderer, FXAAShaderMaterial);
-    // 5.5 ⭐ 外扩环深度测试（补齐此前只定义未调用的死代码）：
-    //   本体深度随描边一起外扩（separable H/V，外扩区取邻域最近深度），
-    //   再用它对外扩后的描边做一次 depthTest。
-    //   缺了这一步，外扩环（描边的视觉主体）永远不参与遮挡判定 →
-    //   物体被挡住时描边依旧从遮挡物前方漏出来（"深度测试看起来失效"的真根因之一）。
-    depthMinBlurShader.uniforms.resolution.value.set(1 / size.x, 1 / size.y);
-    depthMinBlurShader.uniforms.radius.value = Math.max(1, stroke_width);
-    // H：直接采 DepthTexture（selectDepthTexture），其 .r 即对数深度
-    depthMinBlurShader.uniforms.direction.value.set(1, 0);
-    depthMinBlurShader.uniforms.tDepth.value = selectDepthTexture;
-    renderer.setRenderTarget(selectDepthBlurTmpTextureTarget);
-    fsQuad.render(renderer, depthMinBlurShader);
-    // V
-    depthMinBlurShader.uniforms.direction.value.set(0, 1);
-    depthMinBlurShader.uniforms.tDepth.value = selectDepthBlurTmpTextureTarget.texture;
-    renderer.setRenderTarget(selectDepthBlurTextureTarget);
-    fsQuad.render(renderer, depthMinBlurShader);
-    // 调试：记录「外扩后的选区深度」，供面板「深度图（分步）」的步骤 5.5 档读取。
-    // 它是 RGBA8 目标、对数深度存在 .r 里（与 DepthTexture 取 .r 的读法一致）。
-    debugDepthState.lastSelectBlurDepth = selectDepthBlurTextureTarget.texture;
-    // 5.6 对外扩后的描边判遮挡：被更近几何挡住的外扩环像素 discard。
-    //     ⚠️ 输出到独立 target，绝不回写 blur1（历史回归 bug：blur1 被 depthTest 结果覆盖
-    //        会导致步骤 6 相减归零、描边全不显示）。
-    renderer.setRenderTarget(blurDepthTestTextureTarget);
-    renderer.clear();
-    depthTestShader.uniforms.map.value = blur1TextureTarget.texture;
-    depthTestShader.uniforms.baseDepth.value = baseDepthTexture;
-    depthTestShader.uniforms.selectDepth.value = selectDepthBlurTextureTarget.texture;
-    depthTestShader.uniforms.cameraFar.value = camera.far;
-    depthTestShader.uniforms.uDebugVis.value = 0.0;
-    fsQuad.render(renderer, depthTestShader);
-    // 6. 合成：最终外扩描边(blurDepthTest，已判遮挡) 减去 深度测试后的本体描边
-    //    = 仅保留描边外扩环；本体被减掉。filterSelectShader 用 NormalBlending 叠到场景上。
+    // 6. 合成：FXAA 后的外扩描边(blur1) 减去 深度测试后的本体 = 仅保留描边外扩环；本体被减掉。
+    //    ⚠️ 2026-11-04 决定回到「年初口径」：原先这里有 5.5（本体深度随描边一起 separable min-blur 外扩）
+    //    与 5.6（用外扩后的深度再判一次遮挡）两趟，作用是外扩环也参与遮挡判定 ⇒ 物体被挡住时描边不漏光。
+    //    撤掉换来的是每个描边对象每帧全屏绘制 10 趟降 7 趟（min-blur 那两趟是 ±10 共 21 次采样/像素，最贵）；
+    //    代价点名：只有本体参与判遮挡，外扩环不参与 ⇒ 物体贴着遮挡物边缘时，一圈描边会压在遮挡物前面。
     renderer.setRenderTarget(originRenderTarget);
     filterSelectShader.uniforms.selectTexture.value = selectDepthTestTextureTarget.texture;
-    filterSelectShader.uniforms.blurTexture.value = blurDepthTestTextureTarget.texture;
+    filterSelectShader.uniforms.blurTexture.value = blur1TextureTarget.texture;
     filterSelectShader.blending = NormalBlending;
     fsQuad.render(renderer, filterSelectShader);
 }

package/pass/stroke_pass.ts

@@ -44,12 +44,6 @@ const selectDepthTestTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(10
 const blur1TextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, { minFilter: LinearFilter, magFilter: LinearFilter, format: RGBAFormat });
 
 const blur2TextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, { minFilter: LinearFilter, magFilter: LinearFilter, format: RGBAFormat });
-// 外扩深度临时/结果目标：depthMinBlurShader 把本体深度图随描边一起外扩，
-// 外扩区取邻域最近深度（忽略背景 1.0），使外扩区 selD<1.0，depthTest 才能正确判遮挡（不漏光）。
-const selectDepthBlurTmpTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, { minFilter: LinearFilter, magFilter: LinearFilter, format: RGBAFormat });
-const selectDepthBlurTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, { minFilter: LinearFilter, magFilter: LinearFilter, format: RGBAFormat });
-// 外扩描边经深度测试后的结果（步骤 5.6）：独立 target，避免回写 blur1 触发历史回归 bug
-const blurDepthTestTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, { minFilter: LinearFilter, magFilter: LinearFilter, format: RGBAFormat });
 
 const size: Vector2 = new Vector2();
 
@@ -394,53 +388,6 @@ const strokeShader: RawShaderMaterial = new RawShaderMaterial({
     transparent: true
 });
 
-// 深度 min-blur（最近深度，忽略背景 1.0）：随描边一起把深度图向外扩，
-// 外扩区 selD = 物体最近深度(<1.0) 而非清屏 1.0，depthTest 在外扩区才能正确判遮挡（不漏光），
-// 同时本体区仍靠 depthTestShader 的 EPSILON 容差防自遮挡闪烁（无缝）。separable（direction 控制 H/V）。
-const depthMinBlurShader: ShaderMaterial = new ShaderMaterial({
-    uniforms: {
-        tDepth: { value: null },
-        resolution: { value: new Vector2(1 / 512, 1 / 512) },
-        radius: { value: 1.0 },
-        direction: { value: new Vector2(1, 0) },
-    },
-    vertexShader: `
-        ${ShaderChunk.common}
-        ${ShaderChunk.logdepthbuf_pars_vertex}
-        varying vec2 vUv;
-        void main() {
-            vUv = uv;
-            gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
-            ${ShaderChunk.logdepthbuf_vertex}
-        }
-    `,
-    fragmentShader: `
-        ${ShaderChunk.logdepthbuf_pars_fragment}
-        uniform sampler2D tDepth;
-        uniform vec2 resolution;
-        uniform float radius;
-        uniform vec2 direction;
-        varying vec2 vUv;
-        void main() {
-            float minD = 1.0;
-            for (int i = -10; i <= 10; i++) {
-                float x = float(i);
-                vec2 off = direction * (x * radius * resolution);
-                float d = texture2D(tDepth, vUv + off).r;
-                if (d < 0.9999) {
-                    minD = min(minD, d);
-                }
-            }
-            gl_FragColor = vec4(minD, 0.0, 0.0, 1.0);
-            ${ShaderChunk.logdepthbuf_fragment}
-        }
-    `,
-    blending: NoBlending,
-    depthTest: false,
-    depthWrite: false,
-    transparent: true,
-});
-
 const filterSelectShader: RawShaderMaterial = new RawShaderMaterial({
     uniforms: {
         selectTexture: { value: null },
@@ -536,9 +483,6 @@ export default function stroke_pass(
     selectDepthTestTextureTarget.setSize(size.x, size.y);
     blur1TextureTarget.setSize(size.x, size.y);
     blur2TextureTarget.setSize(size.x, size.y);
-    selectDepthBlurTmpTextureTarget.setSize(size.x, size.y);
-    selectDepthBlurTextureTarget.setSize(size.x, size.y);
-    blurDepthTestTextureTarget.setSize(size.x, size.y);
 
     // 1. 渲染物体本体 mask（灰度）。⭐ 本体深度由同一趟光栅化顺带写进 selectDepthTexture
     //   （挂在 selectTextureTarget 的 depth attachment 上）—— 原先这里还有第 2 趟「只渲深度」，
@@ -563,7 +507,8 @@ export default function stroke_pass(
     depthTestShader.uniforms.uDebugVis.value = ((window as unknown as { __STROKE_DEPTH_VIS?: boolean }).__STROKE_DEPTH_VIS) ? 1.0 : 0.0;
     fsQuad.render(renderer, depthTestShader);
 
-    // 4. 从「深度测试后的本体描边」开始外扩（外扩环自动继承本体遮挡判定 → 不漏光），
+    // 4. 从「深度测试后的本体描边」开始外扩（外扩的源头是本体判过的结果，被挡掉的本体不会再长出描边；
+    //    但外扩出来那圈像素本身不再判深度 ⇒ 贴着遮挡物时会压到遮挡物前面，见步骤 6 的代价点名），
     //    描边粗细由 stroke_width 控制的迭代次数决定。
     strokeShader.uniforms.resolution.value.set(1 / size.x, 1 / size.y);
     FXAAShaderMaterial.uniforms.resolution.value.set(1 / size.x, 1 / size.y);
@@ -590,45 +535,14 @@ export default function stroke_pass(
     FXAAShaderMaterial.uniforms.tDiffuse.value = blur2TextureTarget.texture;
     fsQuad.render(renderer, FXAAShaderMaterial);
 
-    // 5.5 ⭐ 外扩环深度测试（补齐此前只定义未调用的死代码）：
-    //   本体深度随描边一起外扩（separable H/V，外扩区取邻域最近深度），
-    //   再用它对外扩后的描边做一次 depthTest。
-    //   缺了这一步，外扩环（描边的视觉主体）永远不参与遮挡判定 →
-    //   物体被挡住时描边依旧从遮挡物前方漏出来（"深度测试看起来失效"的真根因之一）。
-    depthMinBlurShader.uniforms.resolution.value.set(1 / size.x, 1 / size.y);
-    depthMinBlurShader.uniforms.radius.value = Math.max(1, stroke_width);
-    // H：直接采 DepthTexture（selectDepthTexture），其 .r 即对数深度
-    depthMinBlurShader.uniforms.direction.value.set(1, 0);
-    depthMinBlurShader.uniforms.tDepth.value = selectDepthTexture;
-    renderer.setRenderTarget(selectDepthBlurTmpTextureTarget);
-    fsQuad.render(renderer, depthMinBlurShader);
-    // V
-    depthMinBlurShader.uniforms.direction.value.set(0, 1);
-    depthMinBlurShader.uniforms.tDepth.value = selectDepthBlurTmpTextureTarget.texture;
-    renderer.setRenderTarget(selectDepthBlurTextureTarget);
-    fsQuad.render(renderer, depthMinBlurShader);
-
-    // 调试：记录「外扩后的选区深度」，供面板「深度图（分步）」的步骤 5.5 档读取。
-    // 它是 RGBA8 目标、对数深度存在 .r 里（与 DepthTexture 取 .r 的读法一致）。
-    debugDepthState.lastSelectBlurDepth = selectDepthBlurTextureTarget.texture;
-
-    // 5.6 对外扩后的描边判遮挡：被更近几何挡住的外扩环像素 discard。
-    //     ⚠️ 输出到独立 target，绝不回写 blur1（历史回归 bug：blur1 被 depthTest 结果覆盖
-    //        会导致步骤 6 相减归零、描边全不显示）。
-    renderer.setRenderTarget(blurDepthTestTextureTarget);
-    renderer.clear();
-    depthTestShader.uniforms.map.value = blur1TextureTarget.texture;
-    depthTestShader.uniforms.baseDepth.value = baseDepthTexture;
-    depthTestShader.uniforms.selectDepth.value = selectDepthBlurTextureTarget.texture;
-    depthTestShader.uniforms.cameraFar.value = (camera as PerspectiveCamera).far;
-    depthTestShader.uniforms.uDebugVis.value = 0.0;
-    fsQuad.render(renderer, depthTestShader);
-
-    // 6. 合成：最终外扩描边(blurDepthTest，已判遮挡) 减去 深度测试后的本体描边
-    //    = 仅保留描边外扩环；本体被减掉。filterSelectShader 用 NormalBlending 叠到场景上。
+    // 6. 合成：FXAA 后的外扩描边(blur1) 减去 深度测试后的本体 = 仅保留描边外扩环；本体被减掉。
+    //    ⚠️ 2026-11-04 决定回到「年初口径」：原先这里有 5.5（本体深度随描边一起 separable min-blur 外扩）
+    //    与 5.6（用外扩后的深度再判一次遮挡）两趟，作用是外扩环也参与遮挡判定 ⇒ 物体被挡住时描边不漏光。
+    //    撤掉换来的是每个描边对象每帧全屏绘制 10 趟降 7 趟（min-blur 那两趟是 ±10 共 21 次采样/像素，最贵）；
+    //    代价点名：只有本体参与判遮挡，外扩环不参与 ⇒ 物体贴着遮挡物边缘时，一圈描边会压在遮挡物前面。
     renderer.setRenderTarget(originRenderTarget);
     filterSelectShader.uniforms.selectTexture.value = selectDepthTestTextureTarget.texture;
-    filterSelectShader.uniforms.blurTexture.value = blurDepthTestTextureTarget.texture;
+    filterSelectShader.uniforms.blurTexture.value = blur1TextureTarget.texture;
     filterSelectShader.blending = NormalBlending;
     fsQuad.render(renderer, filterSelectShader);
 }

package/threeLoader.d.ts

@@ -9,6 +9,20 @@ import { PLYLoader } from "three/examples/jsm/Addons";
 import type { ThreeLoaderEventMap } from "./EventMap";
 declare class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
     constructor();
+    /** 已经报过的失败地址（去重只服务「计数」，不影响事件本身 —— 事件仍每次发，页面可按 `isNew` 决定要不要提示） */
+    private _failedUrls;
+    /** 全站累计**失败地址数**（与 manager 的 itemsTotal/itemsLoaded 同口径：累加、永不清零 ⇒ 页面自己算「本次」） */
+    loadErrorCount: number;
+    /** 地址 → 服务端回的状态码。只有**拿到过回复**的那两路写得进来：`loadPanoTexture` 的非 2xx（全景整图/32 片切片、平面 4 片）
+     *  与 `loadModel` 的下载失败（GLB 等）。用来把「服务器明说没有」和「断网 / 解码失败」分开 —— 前者页面才敢删数据。 */
+    private _urlStatus;
+    /** 记下一个地址的服务端状态码（键必须与失败上报用的那一个地址串一致） */
+    markUrlStatus(url: string, status: number): void;
+    /** 失败的唯一上报口：`DefaultLoadingManager.onError`（素材那一路）与 `ModelSlot` 那颗 GLB 没出来（模型那一路）都走这里。 */
+    reportLoadError(url: string, kind: "asset" | "model", label?: string): void;
+    /** 从加载器抛出的错误里取 HTTP 状态码，记在**调用方那一个地址**上（`url` 原样，不是内部补全后的地址）。
+     *  three 的 `FileLoader` 非 2xx 抛 `HttpError`（`err.response.status`），个别加载器只把码写进 message。 */
+    private _noteErrStatus;
     getFilename(url: string): string;
     uuid: string;
     anisotropy: number;

package/threeLoader.js

@@ -40,6 +40,12 @@ class ThreeLoader extends EventDispatcher {
         DefaultLoadingManager.onLoad = () => {
             this.onload = true;
         };
+        // 资源加载失败：走 manager 计数的每一条（全景整图/32 片切片、图片平面 4 片、GLB 下载与内嵌贴图）
+        // 都只从这里出，页面侧仍只订本类这一个出口（与 onProgress 同规矩，⛔ 页面不许自己占 manager 的槽位）。
+        // 同一地址去重：全景/平面那两路失败会每帧重发请求 ⇒ 不去重「失败数」会被刷成无穷大。
+        DefaultLoadingManager.onError = (url) => {
+            this.reportLoadError(url, "asset");
+        };
         // 资源替换
         DefaultLoadingManager.setURLModifier((url) => {
             //全路径匹配资源
@@ -58,6 +64,40 @@ class ThreeLoader extends EventDispatcher {
             return new_url;
         });
     }
+    /** 已经报过的失败地址（去重只服务「计数」，不影响事件本身 —— 事件仍每次发，页面可按 `isNew` 决定要不要提示） */
+    _failedUrls = new Set();
+    /** 全站累计**失败地址数**（与 manager 的 itemsTotal/itemsLoaded 同口径：累加、永不清零 ⇒ 页面自己算「本次」） */
+    loadErrorCount = 0;
+    /** 地址 → 服务端回的状态码。只有**拿到过回复**的那两路写得进来：`loadPanoTexture` 的非 2xx（全景整图/32 片切片、平面 4 片）
+     *  与 `loadModel` 的下载失败（GLB 等）。用来把「服务器明说没有」和「断网 / 解码失败」分开 —— 前者页面才敢删数据。 */
+    _urlStatus = new Map();
+    /** 记下一个地址的服务端状态码（键必须与失败上报用的那一个地址串一致） */
+    markUrlStatus(url, status) {
+        if (url)
+            this._urlStatus.set(url, status);
+    }
+    /** 失败的唯一上报口：`DefaultLoadingManager.onError`（素材那一路）与 `ModelSlot` 那颗 GLB 没出来（模型那一路）都走这里。 */
+    reportLoadError(url, kind, label) {
+        const isNew = !this._failedUrls.has(url);
+        if (isNew) {
+            this._failedUrls.add(url);
+            this.loadErrorCount++;
+        }
+        const status = this._urlStatus.get(url);
+        // 403 与 404 并一档：OSS 私有桶里「key 不存在」回的正是 403（AccessDenied 用来不泄露对象是否存在）。
+        const missing = status === 404 || status === 403;
+        this.dispatchEvent({ type: "loadError", url, kind, label, status, missing, failed: this.loadErrorCount, isNew });
+    }
+    /** 从加载器抛出的错误里取 HTTP 状态码，记在**调用方那一个地址**上（`url` 原样，不是内部补全后的地址）。
+     *  three 的 `FileLoader` 非 2xx 抛 `HttpError`（`err.response.status`），个别加载器只把码写进 message。 */
+    _noteErrStatus(url, err) {
+        if (!isString(url))
+            return;
+        const e = err;
+        const raw = e?.status ?? e?.response?.status ?? Number(/(?:responded with|HTTP) (\d{3})/.exec(e?.message ?? "")?.[1]);
+        if (Number.isFinite(raw))
+            this.markUrlStatus(url, raw);
+    }
     // 从url 中提取文件名
     getFilename(url) {
         // 移除URL的查询字符串和哈希部分
@@ -364,7 +404,8 @@ class ThreeLoader extends EventDispatcher {
                     });
                     return res;
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                    this._noteErrStatus(url, err);
                     console.error(`${url},加载失败`);
                     return undefined;
                 });
@@ -381,6 +422,7 @@ class ThreeLoader extends EventDispatcher {
                     return res.scene;
                 })
                     .catch((err) => {
+                    this._noteErrStatus(url, err);
                     // 打印详细错误信息，方便调试
                     console.error(`${url},加载失败`, err);
                     return undefined;
@@ -398,7 +440,8 @@ class ThreeLoader extends EventDispatcher {
                         roughness: 0.5,
                     }));
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                    this._noteErrStatus(url, err);
                     console.error(`${url},加载失败`);
                     return undefined;
                 });
@@ -434,7 +477,8 @@ class ThreeLoader extends EventDispatcher {
                     }
                     return plyMesh;
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                    this._noteErrStatus(url, err);
                     console.error(`${url},加载失败`);
                     return undefined;
                 });
@@ -462,6 +506,7 @@ class ThreeLoader extends EventDispatcher {
                     return res;
                 })
                     .catch((err) => {
+                    this._noteErrStatus(url, err);
                     console.error(`${url},加载失败`, err);
                     return undefined;
                 });

package/threeLoader.ts

@@ -44,6 +44,12 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
         DefaultLoadingManager.onLoad = () => {
             this.onload = true;
         };
+        // 资源加载失败：走 manager 计数的每一条（全景整图/32 片切片、图片平面 4 片、GLB 下载与内嵌贴图）
+        // 都只从这里出，页面侧仍只订本类这一个出口（与 onProgress 同规矩，⛔ 页面不许自己占 manager 的槽位）。
+        // 同一地址去重：全景/平面那两路失败会每帧重发请求 ⇒ 不去重「失败数」会被刷成无穷大。
+        DefaultLoadingManager.onError = (url: string) => {
+            this.reportLoadError(url, "asset");
+        };
         // 资源替换
         DefaultLoadingManager.setURLModifier((url: string) => {
             //全路径匹配资源
@@ -62,6 +68,37 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
             return new_url;
         });
     }
+    /** 已经报过的失败地址（去重只服务「计数」，不影响事件本身 —— 事件仍每次发，页面可按 `isNew` 决定要不要提示） */
+    private _failedUrls: Set<string> = new Set();
+    /** 全站累计**失败地址数**（与 manager 的 itemsTotal/itemsLoaded 同口径：累加、永不清零 ⇒ 页面自己算「本次」） */
+    loadErrorCount: number = 0;
+    /** 地址 → 服务端回的状态码。只有**拿到过回复**的那两路写得进来：`loadPanoTexture` 的非 2xx（全景整图/32 片切片、平面 4 片）
+     *  与 `loadModel` 的下载失败（GLB 等）。用来把「服务器明说没有」和「断网 / 解码失败」分开 —— 前者页面才敢删数据。 */
+    private _urlStatus: Map<string, number> = new Map();
+    /** 记下一个地址的服务端状态码（键必须与失败上报用的那一个地址串一致） */
+    markUrlStatus(url: string, status: number): void {
+        if (url) this._urlStatus.set(url, status);
+    }
+    /** 失败的唯一上报口：`DefaultLoadingManager.onError`（素材那一路）与 `ModelSlot` 那颗 GLB 没出来（模型那一路）都走这里。 */
+    reportLoadError(url: string, kind: "asset" | "model", label?: string): void {
+        const isNew = !this._failedUrls.has(url);
+        if (isNew) {
+            this._failedUrls.add(url);
+            this.loadErrorCount++;
+        }
+        const status = this._urlStatus.get(url);
+        // 403 与 404 并一档：OSS 私有桶里「key 不存在」回的正是 403（AccessDenied 用来不泄露对象是否存在）。
+        const missing = status === 404 || status === 403;
+        this.dispatchEvent({ type: "loadError", url, kind, label, status, missing, failed: this.loadErrorCount, isNew });
+    }
+    /** 从加载器抛出的错误里取 HTTP 状态码，记在**调用方那一个地址**上（`url` 原样，不是内部补全后的地址）。
+     *  three 的 `FileLoader` 非 2xx 抛 `HttpError`（`err.response.status`），个别加载器只把码写进 message。 */
+    private _noteErrStatus(url: string | File | Array<File>, err: unknown): void {
+        if (!isString(url)) return;
+        const e = err as { status?: number; response?: { status?: number }; message?: string };
+        const raw = e?.status ?? e?.response?.status ?? Number(/(?:responded with|HTTP) (\d{3})/.exec(e?.message ?? "")?.[1]);
+        if (Number.isFinite(raw)) this.markUrlStatus(url, raw);
+    }
     // 从url 中提取文件名
     getFilename(url: string): string {
         // 移除URL的查询字符串和哈希部分
@@ -370,7 +407,8 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
                     });
                     return res;
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                        this._noteErrStatus(url, err);
                         console.error(`${url},加载失败`);
                         return undefined;
                     });
@@ -387,6 +425,7 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
                     return res.scene;
                 })
                     .catch((err) => {
+                        this._noteErrStatus(url, err);
                         // 打印详细错误信息，方便调试
                         console.error(`${url},加载失败`, err);
                         return undefined;
@@ -404,7 +443,8 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
                         roughness: 0.5,
                     }));
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                        this._noteErrStatus(url, err);
                         console.error(`${url},加载失败`);
                         return undefined;
                     });
@@ -440,7 +480,8 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
                     }
                     return plyMesh;
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                        this._noteErrStatus(url, err);
                         console.error(`${url},加载失败`);
                         return undefined;
                     });
@@ -467,6 +508,7 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
                     return res;
                 })
                     .catch((err) => {
+                        this._noteErrStatus(url, err);
                         console.error(`${url},加载失败`, err);
                         return undefined;
                     });