如何在react-native中实现兼容Web与移动端的reCaptcha验证码功能

开发者阿泽

2026-9-24

问题原因分析

你遇到的无响应问题核心由WebView内容安全策略拦截导致，reCaptcha验证所需的远程资源被拦截无法加载，因此验证流程卡在加载阶段无后续反馈，控制台的警告也对应该拦截行为。
baseUrl配置错误：该参数必须和你在reCaptcha管理后台申请siteKey时绑定的域名完全一致，随意填写的自定义地址会被reCaptcha服务判定为非法来源，拒绝返回验证资源。
依赖缺失：react-native-recaptcha-that-works依赖react-native-webview作为渲染载体，该依赖为peer依赖不会随库自动安装，未正确安装时会出现加载异常。
缺少错误监听：你当前的组件未配置onError回调，验证流程的报错信息无法被捕获，只能看到无响应的表现，无法定位具体问题。
端侧网络限制：安卓9及以上版本默认禁止明文HTTP请求，如果你的baseUrl为HTTP协议，会被系统默认拦截。

解决方案

修正配置参数
替换代码中的url和key为你实际申请的有效值，baseUrl要和reCaptcha后台绑定的域名完全匹配，本地测试阶段可临时填写https://localhost验证功能。如果你申请的是reCaptcha v3的key，需要额外给组件添加version="v3"参数，版本不匹配也会导致加载失败。
安装缺失依赖
执行如下命令安装react-native-webview：
npm install react-native-webview
如果是iOS环境，安装完成后需要进入ios目录执行pod install更新原生依赖。
补全组件回调参数
给Recaptcha组件添加onError回调捕获报错信息，修改后的参考代码如下：

import React, { useRef } from 'react';
import { View, Button } from 'react-native';
import Recaptcha, { RecaptchaHandles } from "react-native-recaptcha-that-works";

export const Recaptcha_Component = () => {
    // 替换为实际的后台绑定域名和申请的siteKey
    const url = "reCaptcha后台绑定的域名";
    const key = "你申请的reCaptcha公钥";

    const recaptcha = useRef<RecaptchaHandles>(null);

    const send = () => {
        console.log('send!');
        recaptcha.current?.open();
    };

    const onVerify = (token: string) => {
        console.log('success!', token);
        // 拿到token后传给后端做校验即可
    };

    const onExpire = () => {
        console.warn('expired!');
    };

    // 新增错误回调
    const onError = (error: any) => {
        console.error('reCaptcha验证出错：', error);
    };

    return (
        <View>
            <Recaptcha
                ref={recaptcha}
                siteKey={key}
                baseUrl={url}
                onVerify={onVerify}
                onExpire={onExpire}
                onError={onError}
                size={"invisible"}
            />
            <Button title="Send" onPress={send} />
        </View>
    )
}

安卓端网络适配
如果你的baseUrl是HTTP协议地址，需要在安卓原生配置文件android/app/src/main/AndroidManifest.xml的application节点添加android:usesCleartextTraffic="true"属性，允许明文网络请求。
多端兼容适配
如果需要兼容Web端（react-native-web环境），该库的WebView适配存在兼容问题，建议做环境判断，Web端直接使用对应Web端的reCaptcha库实现验证功能，体验更稳定。

内容的提问来源于stack exchange，提问作者Santiago Roa