本地日志

适用于 Whiteboard Web SDK 2.16.59。

本地日志用于定位白板运行问题。Web 接入需要把日志依赖引入项目；只设置 loggerOptions 并不能补齐日志运行时。

安装日志依赖

Shell

npm install agora-foundation@3.11.1

安装 white-web-sdk 的同时安装上述日志包，确保构建输出包含依赖。SDK 自动探测 agora-foundation/lib/logger，通常无需业务另行 import 或直接调用该模块。缺少依赖或 Worker 不可用时会降级，应读取本地日志状态确认。

配置 SDK

TypeScript

const sdk = new WhiteWebSdk({
  appIdentifier, region: "cn-hz",
  loggerOptions: {
  localLog: { enabled: true, enabledUpload: true }
}
});

Web 默认尝试启用本地日志与上传；设 enabled=false 关闭本地日志，enabledUpload=false 只关闭上传。

静态 Worker 资源（按构建环境选择）

若构建工具不能正确发布日志 Worker，可在构建阶段生成并部署与本项目实际 agora-foundation 版本一致的静态 Worker：

Shell

npm install -D esbuild @babel/core @babel/preset-env
npx white-web-sdk-sync-foundation-worker --out public/whiteboard/foundation-worker.js --manifest public/whiteboard/foundation-worker.manifest.json --required --target es5

将命令放到业务构建前，随站点发布生成的静态文件。SDK 配置的 loggerOptions.localLog 中可设置 workerUrl: "/whiteboard/foundation-worker.js"；或在需要自定义 Worker 创建时设置 createWorker: () => new Worker("/whiteboard/foundation-worker.js")，后者优先。URL 应按业务的部署前缀、CSP 与资源可访问性调整。

状态与按需上报

TypeScript

console.log(sdk.getLocalLogState());
try {
  await sdk.flushLocalLogs();
  const result = await sdk.uploadLocalLogs();
  console.log(result);
} catch (error) { console.warn("日志上传失败", error); }

状态查询用于确认运行时是否可用；配置 enabled=true 仍需结合状态确认，不能只据配置判断落盘成功。collectLocalLogs 收集导出结果，不等价于上传；flushLocalLogs 等待缓冲写入；uploadLocalLogs 触发上传，需要等待结果并处理失败。enabledUpload=false 时可以保留本地写入而关闭上传。

TypeScript

const off = sdk.onLocalLogStateChange(state => console.log(state));
// 页面退出时清理监听：
off();

建议在错误反馈流程中按需收集/上传，记录结果并限制重复触发。自定义上传参数和返回字段以客户端 /api-ref/whiteboard/javascript/overview为准；不要把不同平台的回调对象当作相同模型解析。