diff --git a/src/components/image-editor/model3d-preview/Model3dViewerModel.ts b/src/components/image-editor/model3d-preview/Model3dViewerModel.ts
index c5d30f338..600cb5e75 100644
--- a/src/components/image-editor/model3d-preview/Model3dViewerModel.ts
+++ b/src/components/image-editor/model3d-preview/Model3dViewerModel.ts
@@ -44,21 +44,28 @@ export function resolveModel3dDownloadExtension(
 }
 
 /**
- * 查看器失败时给用户看的文案：按失败原因分开说，用早返回写成一列判断。
+ * 查看器失败时给用户看的文案：按失败原因分开说，用 switch 穷尽所有原因。
  * 原因缺失（宿主没拿到 detail）时用调用方的兜底文案。
  */
 export function resolveModel3dViewerFailureText(
   detail: Model3dViewerStatusDetail | null | undefined,
   fallbackText: string,
 ) {
-  if (detail?.reason === 'too-large') {
-    return `模型超过 ${MODEL3D_VIEWER_MAX_MIB} MiB，无法预览。`;
+  switch (detail?.reason) {
+    case 'too-large':
+      return `模型超过 ${MODEL3D_VIEWER_MAX_MIB} MiB，无法预览。`;
+    case 'unsupported-format':
+      return `无法识别模型格式，只支持 ${MODEL3D_VIEWER_SUPPORTED_FORMAT_TEXT}。`;
+    case 'webgl-unavailable':
+      return '当前环境不支持 WebGL2，无法预览模型。';
+    // 加载失败没有更细的可读信息，与原因缺失共用调用方的兜底文案。
+    case 'load-failed':
+    case undefined:
+      return fallbackText;
+    default: {
+      // 查看器新增失败原因时这里会编译报错，不会静默退化成通用文案。
+      const unhandledReason: never = detail?.reason;
+      return unhandledReason;
+    }
   }
-  if (detail?.reason === 'unsupported-format') {
-    return `无法识别模型格式，只支持 ${MODEL3D_VIEWER_SUPPORTED_FORMAT_TEXT}。`;
-  }
-  if (detail?.reason === 'webgl-unavailable') {
-    return '当前环境不支持 WebGL2，无法预览模型。';
-  }
-  return fallbackText;
 }