完善页面8

pages/mall/admin/docs/UNI_APP_X_PAGE_FIX_GUIDE.md

@@ -119,6 +119,37 @@
      - `chart-col` 在桌面端 (>=1200) 使用中等高度 (约 320-360px)。
      - 在移动端/窄屏 (<1200) 自动扩展为大高度 (约 500-600px)，以匹配全宽展示的视觉张力。
 
+#### **原因十九：布局组件依赖缺失导致的级联加载失败**
+
+- **现象**: 控制台报 `GET http://.../AdminLayout.uvue?import net::ERR_CACHE_READ_FAILURE` 或 `TypeError: Failed to fetch dynamically imported module`。
+- **原因**: 核心布局组件（如 `AdminLayout.uvue`）在 `<script setup>` 中使用了 `watch`、`computed` 或其他 Vue API 但**未在顶部 import**。这会导致 JavaScript 语法解析错误，使整个模块加载失败。由于它是所有页面的父容器，会导致全站白屏且报错信息具有误导性（看似网络错误，实为语法错误）。
+- **解决方案**:
+  1. 检查所有在 `setup` 块中使用的 Vue API 是否已显式导入：`import { ref, computed, watch, onMounted } from 'vue'`。
+  2. 使用浏览器的 Network 面板查看失败的 `.uvue?import` 请求详情，查看看具体的语法错误堆栈。
+
+#### **原因二十：UVUE 组件导入路径不规范与生命周期误用**
+
+- **现象**: 页面显示正常但控制台抛出 `Unhandled error during execution of async component loader` 或 `onLoad is not defined`。
+- **原因**:
+  1. **路径缺失后缀**: 在 UVUE 全局构建环境下，导入自定义 `.uvue` 组件必须显式包含 `.uvue` 后缀。
+  2. **生命周期冲突**: 在 `<script setup>` 语法糖中直接编写 `onLoad(() => {})` 而未从 `@dcloudio/uni-app` 导入。
+- **解决方案**:
+  1. **强制后缀**: `import AdminLayout from '@/layouts/admin/AdminLayout.uvue'`。
+  2. **规范生命周期**:
+     - 简单初始化建议统一使用 Vue 标准的 `onMounted(() => {})`。
+     - 如需获取页面参数，通过 `getCurrentPages()` 获取当前页面实例的 `options`。
+     - 禁止在 `setup` 顶层直接定义未声明的 `onLoad/onShow`。
+
+#### **原因二十一：Admin 内部路由 DYNAMIC IMPORT 兼容性问题**
+
+- **现象**: 在 Admin 后台切换菜单或打开特定维护页面时，控制台抛出 `TypeError: Failed to fetch dynamically imported module` 或 `ERR_CACHE_READ_FAILURE`。
+- **原因**:
+  1. **环境限制**: 在某些 `uni-app-x` 的 H5 Vite 编译环境下，针对 `.uvue` 文件的动态 `import()` 支持可能存在不稳定性。
+  2. **语法敏感**: 如果被异步加载的组件本身存在轻微的 UTS/Composition API 语法错误，Vite 的 H5 运行时可能无法正确捕获并提示，而是直接抛出网络加载失败相关的错误。
+- **解决方案**:
+  1. **转为静态导入**: 在 `adminComponentMap.uts` 顶部使用静态 `import` 导入所有管理端子页面组件。
+  2. **组件映射**: 维护 `componentMap` 为静态 Map，避免在运行时使用 `defineAsyncComponent`，从而提高页面的加载成功率和抗语法错误风险。
+
 ## 🛠️ 完整修复流程
 
 ```
@@ -1862,4 +1893,25 @@ const iconMap: Record<string, string> = {
 
 ---
 
-这个指南现在涵盖了 uni-app-x 项目开发中最常见的 15 类问题(新增 CRMEB 路由体系复刻),为后续开发提供了完整的故障排除和最佳实践指导。 🚀
+这个指南现在涵盖了 uni-app-x 项目开发中最常见的 17 类问题(新增动态导入与语法遮蔽解析),为后续开发提供了完整的故障排除和最佳实践指导。 🚀
+
+### 原因二十一：动态导入 (Dynamic Import) 导致 H5 加载异常 (net::ERR_CACHE_READ_FAILURE)
+
+**问题描述：**
+在 H5 环境下，使用 `defineAsyncComponent` 或 Vite 默认的动态导入语法加载 `.uvue` 组件时，经常出现 `net::ERR_CACHE_READ_FAILURE` 错误。这通常是因为 UTS 编译器在处理动态分包时，无法正确生成或缓存对应的脚本模块。
+
+**解决方案：**
+
+1. **强制改为静态导入**：在路由配置文件（如 `adminComponentMap.uts`）中，不要使用 `() => import(...)`，而是直接使用顶层的 `import` 语句导入所有组件。
+2. **中心化映射表**：建立一个中心化的组件映射表，利用 UTS 的强类型特性确保组件在编译期就被分析和包含。
+
+### 原因二十二：语法错误导致模块加载失败 (Masked Syntax Errors)
+
+**问题描述：**
+某些 UTS 语法错误（如非标准的泛型写法 `reactive<T>` 或不兼容的脚本标签 `<script uts>`）在 H5 模式下不会直接报出详细的语法错误，而是会导致生成的 JS 模块无效，从而触发浏览器的 `net::ERR_CACHE_READ_FAILURE`。
+
+**解决方案：**
+
+1. **标准化 Script 标签**：统一使用 `<script setup lang="uts">` 或 `<script lang="uts">`（配合 `defineComponent`）。
+2. **规范响应式声明**：避免在 `reactive` 上直接使用泛型（如 `reactive<T>(...)`），应使用类型断言 `reactive(...) as T`。
+3. **避免遗留的 Options API 写法**：尽量将旧的 `export default { data(), methods() }` 结构转换为 Composition API 模式，以获得最佳的 UTS 编译支持。