开发工具后端【免费下载链接】firebase-js-sdkFirebase Javascript SDK项目地址https://gitcode.com/gh_mirrors/fi/firebase-js-sdk点击查看免费下载RecaptchaVerifier是 Firebase JS SDKfirebase-js-sdk中基于 Google reCAPTCHA 的应用验证器实现是手机号登录、手机号注册等需要人机校验场景的核心组件。本文以 API 参考文档 auth.recaptchaverifier.md 为主体结合packages/auth包源码完整讲解它的构造函数参数、三个核心方法render/verify/clear的用法、与signInWithPhoneNumber的配合方式以及底层运行原理帮助你在实际项目中正确接入并避开常见陷阱。概述RecaptchaVerifier 是什么RecaptchaVerifier是一个基于 reCAPTCHA 的应用验证器Application Verifier它实现了 Firebase Auth 内部定义的ApplicationVerifierInternal接口export declare class RecaptchaVerifier implements ApplicationVerifierInternal在 Firebase Auth 中凡是需要证明操作来自真实用户的敏感操作典型的如手机号登录/注册都必须传入一个实现ApplicationVerifier接口的对象。从源码可见ApplicationVerifier接口只要求两个成员packages/auth/src/model/public_types.tstype验证器类型标识用于区分验证方式verify()执行验证过程并返回一个可用于证明请求有效性的 token。注释中明确指出目前RecaptchaVerifier是该接口的唯一实现。因此它是 Firebase Auth 手机号验证流程中不可绕过的关键组件。需要特别强调的是文档中的一条重要限制RecaptchaVerifierdoes not work in a Node.js environment.即RecaptchaVerifier不能在 Node.js 环境下工作它只面向浏览器Web环境。原因是它依赖document、window等浏览器全局对象以及动态加载外部脚本这一点在源码构造函数与init()方法中都有明确校验见下文运行限制一节。构造函数三个参数的完整语义constructor(authExtern: Auth, containerOrId: HTMLElement | string, parameters?: RecaptchaParameters);参数一authExternAuth 实例对应你的 Firebase Auth 实例即getAuth()的返回值。它用于校验、API 请求以及读取languageCode验证码控件语言会跟随 Auth 实例的语言设置。参数二containerOrId容器reCAPTCHA 挂载的容器可以是DOM 元素HTMLElement也可以是元素的 id 字符串。它的语义随验证码的可见性不同而不同源码构造函数packages/auth/src/platform_browser/recaptcha/recaptcha_verifier.ts是这样解析的const container typeof containerOrId string ? document.getElementById(containerOrId) : containerOrId; _assert(container, this.auth, AuthErrorCode.ARGUMENT_ERROR);三条关键规则若传字符串它必须对应一个已存在于 DOM 中的元素 id初始化时元素必须已在页面上若未找到会抛出argument-error对于可见的 reCAPTCHA非 invisible容器元素必须是空的。源码validateStartingState()中明确断言_assert( this.isInvisible || !this.container.hasChildNodes(), this.auth, AuthErrorCode.ARGUMENT_ERROR );如果容器里已有子节点会直接报错因此在渲染可见验证码前要确保容器内没有任何内容 3. 对于 invisible 验证码容器主要用于承载隐藏的 iframe规则相对宽松。参数三parameters可选 reCAPTCHA 参数可选的 reCAPTCHA 渲染参数类型为 RecaptchaParameters。该接口在源码中是一个开放索引签名packages/auth/src/model/public_types.ts即任意字符串键都可以传入export interface RecaptchaParameters { [key: string]: any; }文档明确说明除sitekey外的所有参数均被接受。sitekey由 Firebase Auth 后端为每个项目预先分配SDK 会在渲染时自动配置用户不要也不能自行传入——若在构造时传了sitekey源码会在validateStartingState()中直接抛出参数错误recaptcha_verifier.ts。如果你不传parametersSDK 会使用如下默认值源码常量 recaptcha_verifier.tsconst DEFAULT_PARAMS: RecaptchaParameters { theme: light, type: image };常用参数均以 reCAPTCHA 官方文档为准参数说明size设为invisible即启用 invisible隐形reCAPTCHA不设置则为可见的复选框样式theme主题light/dark默认lighttype挑战类型image/audio默认imagecallbacktoken 生成后的回调可以是函数也可以是全局函数名字符串源码makeTokenCallback两种都支持expired-callbacktoken 过期时回调SDK 会忽略空 token 过期事件type 属性验证器类型标识readonly type recaptcha;type是只读属性固定值为recaptcha源码常量RECAPTCHA_VERIFIER_TYPErecaptcha_verifier.ts。它用于让 Firebase Auth 后端识别本次验证使用的验证器类型实现ApplicationVerifier接口的协议要求。render()渲染验证码控件render(): Promisenumber;在页面上渲染 reCAPTCHA 控件返回一个resolve 为 reCAPTCHA widget ID 的 Promise。render()的源码实现值得注意recaptcha_verifier.ts若实例已销毁destroyed直接返回一个 rejected Promise若渲染正在进行renderPromise已存在返回同一个 Promise避免重复渲染首次调用时触发内部渲染流程失败后会将renderPromise重置为null允许后续重试。底层渲染流程makeRenderPromise/initrecaptcha_verifier.ts大致为校验当前环境必须为http/https且不是 Web Worker等待 DOM ready动态加载 reCAPTCHA v2 脚本加载细节见下文底层原理调用后端接口getRecaptchaParams获取项目对应的siteKey若是可见验证码SDK 会在容器内再创建一个空的div作为真正的渲染挂载点guaranteedEmpty确保控件渲染不会受容器原内容影响调用grecaptcha.render(container, parameters)得到 widget ID。verify()等待用户完成验证并获取 tokenverify(): Promisestring;等待用户完成 reCAPTCHA 挑战并 resolve 出 reCAPTCHA token一个字符串。这是ApplicationVerifier接口的核心契约也是传给 Firebase 后端证明操作来自真实用户的凭据。源码实现recaptcha_verifier.ts的逻辑很精巧async verify(): Promisestring { this.assertNotDestroyed(); const id await this.render(); const recaptcha this.getAssertedRecaptcha(); const response recaptcha.getResponse(id); if (response) { return response; // 已有 token直接返回 } return new Promisestring(resolve { const tokenChange (token: string): void { if (!token) { return; // 忽略 token 过期事件空 token } this.tokenChangeListeners.delete(tokenChange); resolve(token); }; this.tokenChangeListeners.add(tokenChange); if (this.isInvisible) { recaptcha.execute(id); // invisible 模式需要主动触发执行 } }); }要点如果用户此前已经完成过验证getResponse有值verify()直接复用该 token不会再次弹出验证码否则它注册一个内部 token 监听器等待验证完成空 token过期事件会被忽略继续等待下一次成功验证invisible 模式下会自动调用grecaptcha.execute(id)主动触发隐形验证无需用户点击可见模式下则等待用户勾选/完成挑战后由回调驱动 resolve。clear()清理控件并销毁实例clear(): void;清除页面上的 reCAPTCHA 控件并销毁当前实例。源码实现recaptcha_verifier.tsclear(): void { this.assertNotDestroyed(); this.destroyed true; this._recaptchaLoader.clearedOneInstance(); if (!this.isInvisible) { this.container.childNodes.forEach(node { this.container.removeChild(node); }); } }将实例标记为destroyed此后调用render/verify/clear都会抛出internal-error通知 loader 释放一个实例计数对应ReCaptchaLoaderImpl的counter影响后续脚本复用策略对于可见验证码清空容器内的所有子节点即移除渲染出的控件invisible 模式由于控件承载在 iframe 中不做容器清空。实战与手机号登录signInWithPhoneNumber配合RecaptchaVerifier最典型的应用场景是手机号登录。官方类型注释给出了完整示例packages/auth/src/model/public_types.tsconst recaptchaVerifier new RecaptchaVerifier( auth, recaptcha-container, // 容器 id或直接传 DOM 元素 { size: invisible // 可选使用隐形验证码 } ); // 触发手机号验证码发送RecaptchaVerifier 会自动完成人机验证 const confirmationResult await signInWithPhoneNumber( auth, phoneNumber, recaptchaVerifier ); // 用户输入短信验证码后确认登录 const userCredential await confirmationResult.confirm(verificationCode);完整落地步骤在页面 HTML 中放置容器可见模式必须为空div idrecaptcha-container/div创建验证器并渲染import { getAuth, RecaptchaVerifier, signInWithPhoneNumber } from firebase/auth; const auth getAuth(); const appVerifier new RecaptchaVerifier(auth, recaptcha-container); await appVerifier.render(); // 立即渲染控件也可省略verify 时自动渲染调用signInWithPhoneNumberSDK 内部会自动调用verify()拿到 token 并随请求发送给后端确认验证码confirmationResult.confirm(code)完成登录、绑定或重新认证。集成测试可以佐证这一调用关系packages/auth/test/integration/flows/phone.test.ts中正是先new RecaptchaVerifier(auth, fakeRecaptchaContainer)再将其传入signInWithPhoneNumberphone.test.ts。使用完例如单页应用切换页面时应调用appVerifier.clear()释放资源避免验证码控件残留。底层原理reCAPTCHA 脚本加载与 siteKey 获取脚本动态加载与超时控制RecaptchaVerifier并不会要求你在页面手动引入 reCAPTCHA 脚本而是通过ReCaptchaLoaderImpl动态加载packages/auth/src/platform_browser/recaptcha/recaptcha_loader.ts加载地址为 reCAPTCHA v2 脚本并附加onload回调名、render: explicit显式渲染模式以及hl语言参数取自auth.languageCode网络超时窗口为30~60 秒new Delay(30000, 60000)超时抛network-request-failed若window.grecaptcha.render已存在比如 App Check 等其他模块已加载过 reCAPTCHA会尽量复用而不重复加载避免破坏页面上已渲染的验证码。siteKey 由后端下发你无需也不能提供 siteKey。在init()中 SDK 会调用认证 API 的GET_RECAPTCHA_PARAM端点获取本项目预分配的recaptchaSiteKeypackages/auth/src/api/authentication/recaptcha.tsexport async function getRecaptchaParams(auth: Auth): Promisestring { return ( ( await _performApiRequestvoid, GetRecaptchaParamResponse( auth, HttpMethod.GET, Endpoint.GET_RECAPTCHA_PARAM ) ).recaptchaSiteKey || ); }拿到 siteKey 后才写入this.parameters.sitekey并完成渲染这就是Firebase Auth 后端为每个项目配置 reCAPTCHA的具体实现。测试模式Mock reCAPTCHA在集成测试或使用 Auth 模拟器Emulator时不需要真实加载 Google 验证码服务。SDK 提供了开关auth.settings.appVerificationDisabledForTesting开启该开关后构造函数会选用MockReCaptchaLoaderImplrecaptcha_verifier.ts直接返回一个本地MockReCaptcha不会发起任何网络请求在连接 Auth 模拟器时该开关会被自动置为truepackages/auth/src/core/auth/emulator.ts这就是为什么使用useEmulator后无需处理真实验证码也能跑通手机号登录流程。运行限制与常见错误排查限制/场景说明Node.js 环境不适用。构造时断言typeof document ! undefined无 DOM 直接抛operation-not-supported非 http/https 页面init()中断言_isHttpOrHttps()本地file://等协议无法工作Web Worker显式排除init()会抛internal-error传入sitekey参数构造时抛argument-errorsitekey 由后端下发可见模式容器非空构造时抛argument-error容器必须为空容器 id 不存在构造时抛argument-error销毁后继续使用render/verify/clear抛internal-error网络超时脚本加载 30~60 秒超时后抛network-request-failed小结RecaptchaVerifier是 Firebase Auth 在 Web 端进行人机验证的唯一内置实现构造时传入 Auth 实例、容器与可选参数verify()负责产出验证 tokenrender()控制控件渲染时机clear()负责清理配合signInWithPhoneNumber即可完成手机号登录/注册的安全校验。理解其sitekey 由后端下发、脚本动态加载、测试模式走 Mock这三条实现主线能帮你在真实项目中更快定位与解决问题。相关源码可继续查阅 recaptcha_verifier.ts、recaptcha_loader.ts 与集成测试 phone.test.ts。赞分享开发工具后端【免费下载链接】firebase-js-sdkFirebase Javascript SDK项目地址https://gitcode.com/gh_mirrors/fi/firebase-js-sdk点击查看免费下载相关推荐Firebase JS SDK 深度解析PhoneAuthCredential 手机号验证码凭证的机制与实战Firebase JS SDK 深度解析PhoneAuthCredential 手机号验证码凭证的机制与实战 导读 PhoneAuthCredential 是开发工具后端Firebase JS SDK 核心工具包 firebase/util 完全指南公开 API、源码实现与实战用法Firebase JS SDK 核心工具包 firebase/util 完全指南公开 API、源码实现与实战用法 导读 firebase/util 是 F开发工具后端Firebase JS SDK 的 ApplicationVerifier 接口从接口契约到 reCAPTCHA 实战Firebase JS SDK 的 ApplicationVerifier 接口从接口契约到 reCAPTCHA 实战 ApplicationVerifier开发工具后端上一篇5分钟精通biliTickerBuyB站会员购抢票开源工具终极指南下一篇前端路由性能优化history库高级应用技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考