diff --git a/sdk-webview/src/main/java/com/xuqm/sdk/webview/XWebViewTypes.kt b/sdk-webview/src/main/java/com/xuqm/sdk/webview/XWebViewTypes.kt
index e46bfe4..c4b9ba3 100644
--- a/sdk-webview/src/main/java/com/xuqm/sdk/webview/XWebViewTypes.kt
+++ b/sdk-webview/src/main/java/com/xuqm/sdk/webview/XWebViewTypes.kt
@@ -16,6 +16,8 @@ data class XWebViewConfig(
     /** When non-null, shows a status-bar progress notification with this title while downloading. */
     val downloadNotificationTitle: String? = null,
     val onMessage: ((String) -> Unit)? = null,
+    /** 页面加载失败时回调。errorCode / description / failingUrl 对应 WebViewClient.onReceivedError 参数。 */
+    val onPageError: ((errorCode: Int, description: String, failingUrl: String) -> Unit)? = null,
 )
 
 interface XWebViewController {
diff --git a/sdk-webview/src/main/java/com/xuqm/sdk/webview/XWebViewView.kt b/sdk-webview/src/main/java/com/xuqm/sdk/webview/XWebViewView.kt
index f2ecb66..a2c321f 100644
--- a/sdk-webview/src/main/java/com/xuqm/sdk/webview/XWebViewView.kt
+++ b/sdk-webview/src/main/java/com/xuqm/sdk/webview/XWebViewView.kt
@@ -16,6 +16,7 @@ import android.webkit.MimeTypeMap
 import android.webkit.PermissionRequest
 import android.webkit.ValueCallback
 import android.webkit.WebChromeClient
+import android.webkit.WebResourceError
 import android.webkit.WebResourceRequest
 import android.webkit.WebViewClient
 import android.webkit.WebView
@@ -532,6 +533,18 @@ fun XWebViewView(
                         openExternalScheme(ctx, uri)
                         return true
                     }
+
+                    override fun onReceivedError(view: WebView?, request: WebResourceRequest?, error: WebResourceError?) {
+                        super.onReceivedError(view, request, error)
+                        // 仅处理主框架加载错误（忽略子资源如图片、JS 等）
+                        if (request?.isForMainFrame == true) {
+                            val code = error?.errorCode ?: -1
+                            val desc = error?.description?.toString() ?: "Unknown error"
+                            val url = request.url?.toString() ?: ""
+                            android.util.Log.e("XWV", "onReceivedError: code=$code, desc=$desc, url=$url")
+                            mainHandler.post { config.onPageError?.invoke(code, desc, url) }
+                        }
+                    }
                 }
 
                 webChromeClient = object : WebChromeClient() {