鸿蒙 Web组件常见报错排查

本文同步发表于我的微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

一、基础检查

1. 检查错误日志

// 在Web组件中设置错误监听
@Entry
@Component
struct WebPage {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'https://example.com', controller: this.controller })
        .onError(event => {
          console.error('Web组件错误:', 
            `错误类型: ${event.errorType}, 
             错误码: ${event.errorCode}, 
             描述: ${event.description}`)
        })
    }
  }
}

常见错误类型和错误码：

• -1: 未知错误
• -2: 主机名解析失败
• -3: 连接超时
• -4: 无效URL
• -5: HTTP错误(如404, 500等)
• -6: SSL证书错误

2. 检查网络权限

在module.json5中确认已添加网络权限：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "reason": "用于Web组件访问网络"
      }
    ]
  }
}

3. 验证URL有效性

function isValidUrl(url: string): boolean {
  try {
    new URL(url);
    return true;
  } catch (e) {
    return false;
  }
}

// 使用示例
const url = 'https://example.com';
if (!isValidUrl(url)) {
  console.error('无效的URL:', url);
}

二、常见问题解决

1. 页面加载失败

现象：

• 白屏或显示"网页无法打开"
• 控制台输出onError回调

// 1. 添加加载状态处理
Web({ src: 'https://example.com', controller: this.controller })
  .onPageBegin(() => {
    console.log('页面开始加载');
    // 显示加载指示器
  })
  .onPageEnd(() => {
    console.log('页面加载完成');
    // 隐藏加载指示器
  })
  .onProgressChange(progress => {
    console.log(`加载进度: ${progress}%`);
  })

// 2. 实现重试机制
@State retryCount: number = 0;

private retryLoad() {
  if (this.retryCount < 3) {
    this.retryCount++;
    this.controller.refresh();
  }
}

2. SSL证书问题

现象：

• 控制台报SSL错误(错误码-6)
• HTTPS网站无法加载

// 1. 忽略SSL错误(仅限测试环境)
Web({ src: 'https://example.com', controller: this.controller })
  .onSslErrorEvent(event => {
    console.warn('SSL证书错误:', event);
    event.handler.handleConfirm(); // 继续加载
    // 生产环境应使用event.handler.handleCancel()
  })

// 2. 正确配置证书
// 确保服务器使用有效证书
// 对于自签名证书，考虑使用合法CA或配置证书钉扎

3. 跨域问题

现象：

• 控制台报跨域错误
• AJAX请求失败

// 1. 在Web组件中启用JavaScript和DOM存储
Web({ /* ... */ })
  .javaScriptAccess(true)
  .domStorageAccess(true)

// 2. 服务器端配置CORS头
// Access-Control-Allow-Origin: *
// Access-Control-Allow-Methods: GET, POST
// Access-Control-Allow-Headers: Content-Type

// 3. 使用鸿蒙网络请求替代页面内AJAX
import http from '@ohos.net.http';

function fetchData(url: string) {
  const httpRequest = http.createHttp();
  httpRequest.request(url, {
    method: 'GET',
    connectTimeout: 60000,
    readTimeout: 60000,
  }, (err, data) => {
    if (err) {
      console.error('请求失败:', err);
    } else {
      console.log('请求成功:', data.result);
      // 通过evaluateJavascript注入到页面
      this.controller.runJavaScript(`updateData(${JSON.stringify(data.result)})`);
    }
  });
}

4. 内存泄漏

现象：

• 应用内存持续增长
• 页面切换后Web组件未正确释放

// 1. 在页面销毁时清理资源
aboutToDisappear() {
  this.controller.destroy();
}

// 2. 使用单一WebController实例
// 避免重复创建

// 3. 监控内存使用
import system from '@ohos.system.memory';

function checkMemoryUsage() {
  system.getMemoryInfo().then(data => {
    console.log(`内存使用: ${JSON.stringify(data)}`);
    if (data.availMem / data.totalMem < 0.2) {
      console.warn('内存不足，建议清理资源');
    }
  });
}

三、调试技巧

1. 启用远程调试

// 1. 启用调试
Web({ /* ... */ })
  .webDebuggingAccess(true)

// 2. 在Chrome中访问 chrome://inspect
// 3. 选择你的设备进行调试

2. 控制台日志拦截

Web({ /* ... */ })
  .onConsole(event => {
    console.log(`网页控制台: [${event.messageLevel}] ${event.message}`);
    // 可根据日志级别过滤
    switch(event.messageLevel) {
      case ConsoleMessageLevel.DEBUG:
        // 处理调试日志
        break;
      case ConsoleMessageLevel.ERROR:
        // 处理错误日志
        break;
    }
  })

3. JavaScript交互调试

// 1. 执行JavaScript代码
this.controller.runJavaScript('document.title')
  .then(result => {
    console.log('执行结果:', result);
  })
  .catch(error => {
    console.error('执行错误:', error);
  });

// 2. 注册JavaScript处理器
this.controller.registerJavaScriptProxy({
  showToast: (message) => {
    prompt.showToast({ message });
  }
}, 'nativeBridge');

// 在网页中调用: window.nativeBridge.showToast("Hello");

4. 性能监控

// 1. 启用性能监控
Web({ /* ... */ })
  .onPerformanceDataUpdate(event => {
    console.log('性能数据:', 
      `DNS查询: ${event.dnsLookupTime}ms, 
       TCP连接: ${event.tcpConnectTime}ms,
       页面加载: ${event.pageLoadTime}ms`);
  })

// 2. 手动获取性能指标
this.controller.getWebPerformance().then(perf => {
  console.log('网页性能指标:', perf);
});

四、系统级问题排查

1. 检查WebView版本

import webview from '@ohos.web.webview';

function checkWebViewVersion() {
  console.log('WebView版本:', webview.getWebViewVersion());
  // 最低支持版本检查
  if (webview.compareVersion('1.0.0') < 0) {
    console.error('WebView版本过低');
  }
}

2. 系统WebView设置

// 1. 检查WebView全局设置
webview.setWebViewSettings({
  javaScriptEnabled: true,
  cacheMode: webview.WebCacheMode.DEFAULT,
  zoomAccess: true
});

// 2. 清除缓存(谨慎使用)
webview.clearCache(true);
webview.clearHistory();

3. 系统兼容性检查

function checkSystemCompatibility() {
  const systemInfo = system.getSystemInfoSync();
  console.log('系统信息:', systemInfo);
  
  // 检查API版本
  if (systemInfo.apiVersion < 8) {
    console.error('当前系统版本不支持某些Web组件功能');
  }
}

五、问题记录

1. 创建错误报告

function generateErrorReport(error: any): string {
  return JSON.stringify({
    timestamp: new Date().toISOString(),
    deviceInfo: system.getSystemInfoSync(),
    webViewVersion: webview.getWebViewVersion(),
    errorDetails: {
      type: error.errorType,
      code: error.errorCode,
      description: error.description,
      url: error.url
    },
    networkState: {
      type: connectivity.getNetworkType(),
      isConnected: connectivity.isConnected()
    }
  });
}

2. 提交反馈

function submitErrorReport(errorReport: string) {
  const httpRequest = http.createHttp();
  httpRequest.request('https://your-error-report-api.com', {
    method: 'POST',
    extraData: errorReport,
    header: { 'Content-Type': 'application/json' }
  }, (err, data) => {
    if (err) {
      console.error('提交错误报告失败:', err);
    } else {
      console.log('错误报告已提交');
    }
  });
}