# 加载、缓存与诊断参考
动态加载、优先级、overrides、缓存、样式和运行时观察。
## 选择加载层级
完整生命周期使用 `wu.mount`。`wu.prefetch` 提前请求已注册应用资源，`wu.use` 加载通过 exports 发布的组件。`WuLoader` 是独立加载器，不替代 core 的目录、sandbox 或 grants。
Overrides 和检查工具属于宿主。指标衡量观察到的某段过程，不保证浏览器已完成绘制。完整流程请参阅[应用加载](/zh-cn/docs/framework/loading/)和[诊断](/zh-cn/docs/framework/troubleshooting/)。
## wu.use
加载另一应用声明的组件 export。
`wu.use("app.component"): Promise`
- **参数：** 精确名称 app.component；提供方 manifest 必须声明 wu.exports。
- **返回值：** 存在时为 default export，否则为模块 namespace。
- **错误：** 应用/export 缺失、目录穿越、无效 URL 或导入失败会拒绝。
- **权限：** 宿主；加载组件在消费方 realm 内执行代码。
- **清理：** 使用组件的 renderer 实例负责管理 cleanup。
```js
const ProductCard = await wu.use('catalog.ProductCard');
```
运行时存在此方法，但 WuCore 声明缺失。它不会在不同框架之间转换组件。
参考：`src/core/wu-core.js`.
## wu.prefetchAll
请求预加载全部已注册应用。
`wu.prefetchAll(options?): Promise | (() => void)`
- **参数：** 与 prefetch 相同的触发选项。
- **返回值：** 即时 Promise 或延迟触发器 cleanup。
- **错误：** 预加载是向浏览器发出请求，不确认 renderer 能挂载。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 选择延迟触发器时保存 cleanup。
```js
await wu.prefetchAll({ on: 'immediate' });
```
参考：`src/core/wu-prefetch.js`.
## new WuLoader
创建具备缓存和进行中请求去重的代码与组件 loader。
`new WuLoader({ maxCacheSize?, cacheTTL? }?): WuLoader`
- **参数：** maxCacheSize 限制条目数量，默认 50；cacheTTL 单位毫秒，默认 1800000。
- **返回值：** 包含 loadApp、loadComponent、preload、isAvailable 和 clearCache 的实例。
- **错误：** 创建不会注册应用或执行生命周期。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** loader.clearCache() 释放缓存条目。
```js
import { WuLoader } from 'wu-framework';
const loader = new WuLoader({ maxCacheSize: 20, cacheTTL: 60000 });
```
参考：`src/core/wu-loader.js`.
## WuLoader.loadApp
下载入口代码文本，供加载流程使用。
`loader.loadApp(appUrl, manifest?): Promise`
- **参数：** 基础 URL 和带可选 entry 的 manifest。
- **返回值：** 代码字符串；不执行 mount，也不注册应用。
- **错误：** Fetch 失败、无效响应或 entry 解析失败会拒绝。
- **权限：** 宿主，受环境网络访问限制。
- **清理：** clearCache(base) 丢弃供后续读取复用的缓存。
```js
const code = await loader.loadApp('/apps/catalog', { entry: 'entry.js' });
```
参考：`src/core/wu-loader.js`.
## WuLoader.loadComponent
导入限制在应用基础目录内的组件。
`loader.loadComponent(appUrl, componentPath): Promise`
- **参数：** 基础地址和组件相对路径；不允许绝对 URL 或目录穿越。
- **返回值：** default export 或导入 namespace。
- **错误：** 路径超出基础目录或导入失败时拒绝。
- **权限：** 模块在同一上下文执行代码，不是 scoped RPC。
- **清理：** 原生 import 保留模块缓存。
```js
const card = await loader.loadComponent('/apps/catalog', 'components/card.js');
```
参考：`src/core/wu-loader.js`.
## WuLoader.preload
为应用列表提前下载代码。
`loader.preload(appConfigs: WuAppConfig[]): Promise`
- **参数：** 包含 name 和 url 的配置数组。
- **返回值：** 预加载遍历完成的 Promise。
- **错误：** 预加载逐个捕获应用失败；挂载前检查可用性。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 不挂载 renderers；clearCache 释放缓存文本。
```js
await loader.preload([{ name: 'catalog', url: '/apps/catalog' }]);
```
参考：`src/core/wu-loader.js`.
## WuLoader.isAvailable
查询 URL 是否正确响应 HEAD。
`loader.isAvailable(url): Promise`
- **参数：** 待检查 URL。
- **返回值：** 布尔值，网络错误转换为 false。
- **错误：** 服务器拒绝 HEAD 时，即使 GET 可用也可能返回 false。
- **权限：** 宿主网络访问。
- **清理：** 不创建订阅或持久进程。
```js
const available = await loader.isAvailable('/apps/catalog/entry.js');
```
参考：`src/core/wu-loader.js`.
## WuLoader.clearCache
丢弃 loader 缓存的文本和记录。
`loader.clearCache(pattern?): void`
- **参数：** 可选模式；无模式时清空 loader 缓存。
- **返回值：** void。
- **错误：** 不使浏览器 ESM 缓存失效。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 不创建订阅或持久进程。
```js
loader.clearCache('catalog');
```
参考：`src/core/wu-loader.js`.
## WuLoader.getStats
查询 loader 缓存和进行中的 imports。
`loader.getStats(): object`
- **参数：** 无参数。
- **返回值：** 指标对象。
- **错误：** 不代表应用挂载状态。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 不创建订阅或持久进程。
```js
console.log(loader.getStats());
```
参考：`src/core/wu-loader.js`.
## wu.override
配置开发用 URL 替换。
`wu.override(name, url, options?): void`
- **参数：** name 和已授权 URL；options.maxAge/path 配置 override 持久化。
- **返回值：** void
- **错误：** 系统验证域名和配置；override 不会自动 remount。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 共享会话前移除开发 overrides。
```js
wu.override('catalog', 'http://localhost:4101');
```
参考：`src/core/wu-overrides.js`.
## wu.removeOverride
移除 URL 替换。
`wu.removeOverride(name): void`
- **参数：** 精确应用名称。
- **返回值：** void
- **错误：** 系统验证域名和配置；override 不会自动 remount。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 共享会话前移除开发 overrides。
```js
wu.removeOverride('catalog');
```
参考：`src/core/wu-overrides.js`.
## wu.getOverrides
查询活动 URL 替换。
`wu.getOverrides(): Record`
- **参数：** 无参数。
- **返回值：** Record
- **错误：** 系统验证域名和配置；override 不会自动 remount。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 共享会话前移除开发 overrides。
```js
console.log(wu.getOverrides());
```
参考：`src/core/wu-overrides.js`.
## wu.clearOverrides
移除全部活动替换。
`wu.clearOverrides(): void`
- **参数：** 无参数。
- **返回值：** void
- **错误：** 系统验证域名和配置；override 不会自动 remount。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 共享会话前移除开发 overrides。
```js
wu.clearOverrides();
```
参考：`src/core/wu-overrides.js`.
## normalizeStyleMode
规范化样式配置别名。
`normalizeStyleMode(mode): string | undefined`
- **参数：** 模式字符串或 undefined。
- **返回值：** none→isolated；own-only→fully-isolated；其他值不验证直接传递。
- **错误：** 本身不验证 manifest 是否允许该模式。
- **权限：** 纯函数，不授予权限。
- **清理：** 不创建订阅或持久进程。
```js
import { normalizeStyleMode } from 'wu-framework';
console.log(normalizeStyleMode('own-only'));
```
参考：`src/core/wu-sandbox.js`.
## resolveDomOwnership
解析显式所有权及 nativeShadow/framework 别名。
`resolveDomOwnership(options?): "wu" | "app" | "light"`
- **参数：** domOwnership 优先，其次 nativeShadow；Lit 默认选择 app。
- **返回值：** 实际生效的所有权。
- **错误：** 不创建 Shadow DOM，也不验证 renderer 是否实现其边界。
- **权限：** 配置函数，不是安全控制。
- **清理：** 不创建订阅或持久进程。
```js
import { resolveDomOwnership } from 'wu-framework';
console.log(resolveDomOwnership({ framework: 'lit' }));
```
参考：`src/core/wu-sandbox.js`.
## wu.tagStyleAsApp
为 CSS bridge 将 style/link 样式表归属到应用。
`wu.tagStyleAsApp(element, appName): void`
- **参数：** style/link 元素和应用名称。
- **返回值：** void。
- **错误：** 归属标记不能替代 manifest 的 styleMode。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 所属者结束时移除样式表。
```js
const style = document.createElement('style');
style.textContent = ':host { color: var(--accent); }';
wu.tagStyleAsApp(style, 'catalog');
document.head.append(style);
```
参考：`src/core/wu-core.js`.
## new WuCache
创建带 TTL 和可选存储的 LRU 缓存。
`new WuCache(options?): WuCache`
- **参数：** maxSize 单位 MB；maxItems；TTL 单位 ms；persistent，以及 memory/localStorage/sessionStorage 类型的 storage。
- **返回值：** 缓存实例。
- **错误：** 条目过大或操作限额可能阻止存储。
- **权限：** 宿主；不要用持久存储作为授权。
- **清理：** cache.clear() 释放条目和持久 namespace。
```js
import { WuCache } from 'wu-framework';
const cache = new WuCache({ maxSize: 2, maxItems: 20, defaultTTL: 60000, storage: 'memory' });
```
参考：`src/core/wu-cache.js`.
## WuCache.get
读取未过期条目并更新 LRU 顺序。
`cache.get(key): unknown | null`
- **参数：** 条目键。
- **返回值：** 保存值；缺失、过期或 rate limit 时为 null。
- **错误：** null 无法区分 miss、过期或 cooldown，请查看指标。
- **权限：** 访问所属缓存，不应用 store grants。
- **清理：** 不创建订阅或持久进程。
```js
const result = cache.get('catalog-result');
```
内存读取返回保存的引用，不像 WuStore 那样返回独立快照。
参考：`src/core/wu-cache.js`.
## WuCache.set
保存值并应用空间和过期限制。
`cache.set(key, value, ttl?): boolean`
- **参数：** 键、值及毫秒 TTL；由于使用 ||，ttl=0 会采用 defaultTTL。
- **返回值：** 存储成功为 true；大小、错误或 rate limit 导致 false。
- **错误：** 捕获失败并返回 false；storage 配额可能限制持久化。
- **权限：** 宿主；验证要持久保存的数据。
- **清理：** delete(key) 移除一条，clear() 移除全部。
```js
const cached = cache.set('catalog-result', { count: 12 }, 30000);
```
参考：`src/core/wu-cache.js`.
## WuCache.delete
从内存及配置的后端存储删除条目。
`cache.delete(key): void`
- **参数：** 精确键。
- **返回值：** void
- **错误：** 持久化取决于 storage 可用性和配额。
- **权限：** 缓存所属者的权限。
- **清理：** 不创建订阅或持久进程。
```js
cache.delete('catalog-result');
```
参考：`src/core/wu-cache.js`.
## WuCache.clear
清空此实例缓存及配置的存储。
`cache.clear(): void`
- **参数：** 无参数。
- **返回值：** void
- **错误：** 持久化取决于 storage 可用性和配额。
- **权限：** 缓存所属者的权限。
- **清理：** 不创建订阅或持久进程。
```js
cache.clear();
```
参考：`src/core/wu-cache.js`.
## WuCache.getStats
查询 hits、misses、evictions、大小和 rate limiting。
`cache.getStats(): object`
- **参数：** 无参数。
- **返回值：** object
- **错误：** 持久化取决于 storage 可用性和配额。
- **权限：** 缓存所属者的权限。
- **清理：** 不创建订阅或持久进程。
```js
console.log(cache.getStats());
```
参考：`src/core/wu-cache.js`.
## WuCache.getRateLimitStatus
查询操作是否处于 cooldown 及其配额。
`cache.getRateLimitStatus(): object`
- **参数：** 无参数。
- **返回值：** object
- **错误：** 持久化取决于 storage 可用性和配额。
- **权限：** 缓存所属者的权限。
- **清理：** 不创建订阅或持久进程。
```js
console.log(cache.getRateLimitStatus());
```
参考：`src/core/wu-cache.js`.
## wu.getStats
汇总 core 各子系统状态和指标。
`wu.getStats(): object`
- **参数：** 无参数。
- **返回值：** 诊断对象。
- **错误：** 不替代挂载测试或 HTTP 检查。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 不创建订阅或持久进程。
```js
console.log(wu.getStats());
```
参考：`src/core/wu-core.js`.
## wu.getManifestDiagnostics
读取应用间声明式依赖错误。
`wu.getManifestDiagnostics(): WuManifestImportDiagnostic[]`
- **参数：** 无参数；依赖 imports preflight。
- **返回值：** 按消费者/import/提供方组织的诊断列表。
- **错误：** 不自动检查 bundle 全部传递 imports。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 不创建订阅或持久进程。
```js
console.table(wu.getManifestDiagnostics());
```
参考：`src/core/wu-core.js`.
## wu.showInspector
打开按需加载的可视检查器。
`wu.showInspector(): Promise<{ close(): void } | null>`
- **参数：** 无参数。
- **返回值：** close handle，未打开时为 null。
- **错误：** chunk 加载或 DOM 环境可能阻止打开。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** close() 或 wu.hideInspector() 移除 overlay。
```js
const inspector = await wu.showInspector();
// Al cerrar tu herramienta:
inspector?.close();
```
参考：`src/core/wu-core.js`.
## wu.hideInspector
若存在检查 overlay，则关闭。
`wu.hideInspector(): Promise`
- **参数：** 无参数。
- **返回值：** 关闭 Promise。
- **错误：** 不删除应用或 store 数据。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 移除诊断界面。
```js
await wu.hideInspector();
```
参考：`src/core/wu-core.js`.
## wu.performance.startMeasure
标记应用或全局耗时测量的起点。
`wu.performance.startMeasure(name, appName?): void`
- **参数：** 测量名称；appName 默认为 global。
- **返回值：** void。
- **错误：** disabled 配置会跳过记录。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 使用同一名称/应用调用 endMeasure。
```js
wu.performance.startMeasure('load-catalog', 'catalog');
```
参考：`src/core/wu-performance.js`.
## wu.performance.endMeasure
结束耗时测量，启用时发布到指标和 User Timing。
`wu.performance.endMeasure(name, appName?): number`
- **参数：** 与 startMeasure 相同的名称/应用。
- **返回值：** 毫秒数；没有起始标记则为 0。
- **错误：** 缺少标记返回 0，不虚构时长。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 移除此测量的起始标记。
```js
const ms = wu.performance.endMeasure('load-catalog', 'catalog');
```
参考：`src/core/wu-performance.js`.
## wu.performance.generateReport
汇总实例性能统计。
`wu.performance.generateReport(): object`
- **参数：** 无参数。
- **返回值：** object
- **错误：** User Timing 可用性取决于环境。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 不创建订阅或持久进程。
```js
console.log(wu.performance.generateReport());
```
参考：`src/core/wu-performance.js`.
## wu.performance.getMetrics
读取特定应用指标。
`wu.performance.getMetrics(appName): object | null`
- **参数：** 精确名称；没有测量时为 null。
- **返回值：** object | null
- **错误：** User Timing 可用性取决于环境。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 不创建订阅或持久进程。
```js
console.log(wu.performance.getMetrics('catalog'));
```
参考：`src/core/wu-performance.js`.
## wu.performance.getAllMetrics
读取测量器中所有应用的指标。
`wu.performance.getAllMetrics(): object`
- **参数：** 无参数。
- **返回值：** object
- **错误：** User Timing 可用性取决于环境。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 不创建订阅或持久进程。
```js
console.log(wu.performance.getAllMetrics());
```
参考：`src/core/wu-performance.js`.
## wu.performance.clearMetrics
清除一个或所有应用的测量。
`wu.performance.clearMetrics(appName?): void`
- **参数：** 可选名称。
- **返回值：** void
- **错误：** User Timing 可用性取决于环境。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 不创建订阅或持久进程。
```js
wu.performance.clearMetrics('catalog');
```
参考：`src/core/wu-performance.js`.
## wu.performance.getDevToolsEntries
读取 WU 发出的 User Timing 条目。
`wu.performance.getDevToolsEntries(options?): PerformanceEntry[]`
- **参数：** type 为 mark、measure 或 all；appName 可选。
- **返回值：** PerformanceEntry[]
- **错误：** User Timing 可用性取决于环境。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 不创建订阅或持久进程。
```js
console.table(wu.performance.getDevToolsEntries({ type: 'measure', appName: 'catalog' }));
```
参考：`src/core/wu-performance.js`.
## wu.performance.observe
通过 PerformanceObserver 监听新的 WU User Timing 条目。
`wu.performance.observe(callback, { type? }?): () => void`
- **参数：** PerformanceEntry 回调；type 默认为 measure。
- **返回值：** Cleanup；observer 不可用时返回空函数。
- **错误：** 缺少 PerformanceObserver 不抛出，回调失败会记录。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** stop() 断开 observer。
```js
const stop = wu.performance.observe(entry => console.log(entry.duration), { type: 'measure' });
```
参考：`src/core/wu-performance.js`.
## wu.performance.configure
配置测量、历史上限、User Timing 和阈值。
`wu.performance.configure(options): void`
- **参数：** enabled、maxMeasurements、devtoolsTimeline 和按名称配置的 thresholds。
- **返回值：** void。
- **错误：** 超出阈值产生警告，不取消操作。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 不创建订阅或持久进程。
```js
wu.performance.configure({ enabled: true, maxMeasurements: 100, devtoolsTimeline: true });
```
参考：`src/core/wu-performance.js`.
## wu.errorBoundary.register
添加故障分类与恢复处理函数。
`wu.errorBoundary.register(handler): void`
- **参数：** name、canHandle(error) 和 handle(error,context)。
- **返回值：** void。
- **错误：** 缺少任何成员会抛出；按顺序遍历 handlers。
- **权限：** 宿主 API，scoped facade 不暴露。
- **清理：** 不返回 unsubscribe；在宿主生命周期内管理这些扩展。
```js
wu.errorBoundary.register({ name: 'catalog-error', canHandle: error => error.name === 'CatalogError', async handle(error) { return { recovered: false, action: 'none', message: error.message }; } });
```
默认通用 fallback 可能先于后添加的 handlers。依赖此注册前检查顺序。
参考：`src/core/wu-error-boundary.js`.
## wu.errorBoundary.handle
分类故障并获得恢复决定。
`wu.errorBoundary.handle(error, context?): Promise