Android端Capacitor/Angular应用SSL握手失败问题求助

错误分析 #

你遇到的[ERROR:ssl_client_socket_impl.cc(879)] handshake failed; returned -1, SSL error code 1, net_error -202是Android WebView不信任Capacitor本地HTTPS服务的自签证书导致的握手失败。而添加android:usesCleartextTraffic="true"后出现的版本警告，是因为该属性仅在API 23+生效，你的项目最低支持API 22，所以系统提示该配置在低版本上无效。

解决步骤 #

1. 信任本地HTTPS证书（核心修复） #

Capacitor默认用HTTPS加载本地资源，WebView默认拒绝自签证书，需在Android代码中配置信任localhost的SSL证书：

• 打开Android项目的MainActivity.java（或MainActivity.kt）
• 在onCreate方法中添加WebView证书信任逻辑：

import com.getcapacitor.Bridge;
import com.getcapacitor.BridgeWebViewClient;
import com.getcapacitor.CapacitorWebView;
import android.webkit.SslError;
import android.webkit.SslErrorHandler;
import android.webkit.WebView;

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // 初始化Capacitor插件（保留原有插件配置）
    this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{
        // 这里添加你的Capacitor插件，比如add(GoogleAuthPlugin.class);
    }});

    // 配置WebView信任本地localhost的SSL证书
    CapacitorWebView webView = getBridge().getWebView();
    webView.setWebViewClient(new BridgeWebViewClient(getBridge()) {
        @Override
        public void onReceivedSslError(WebView view, SslErrorHandler handler, SslError error) {
            // 仅信任localhost的HTTPS请求，其他地址仍按默认逻辑处理
            if (error.getUrl().startsWith("https://localhost")) {
                handler.proceed();
            } else {
                super.onReceivedSslError(view, handler, error);
            }
        }
    });
}

2. 替换usesCleartextTraffic解决版本警告（若需明文HTTP） #

如果应用需要访问HTTP明文接口，同时兼容API 22及以下，用网络安全配置文件替代usesCleartextTraffic：

• 在res/xml目录创建network_security_config.xml：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="system" />
        </trust-anchors>
    </base-config>
</network-security-config>

• 在AndroidManifest.xml的<application>标签中引用该配置，移除原android:usesCleartextTraffic="true"：

<application
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:roundIcon="@mipmap/ic_launcher_round"
    android:supportsRtl="true"
    android:networkSecurityConfig="@xml/network_security_config">
    <!-- 其他配置 -->
</application>

3. 验证修复 #

重新构建Android项目并运行，检查控制台是否还有SSL握手错误，同时确认接口请求正常。

内容的提问来源于stack exchange，提问作者Darshika Siemens