v3 的核心是在提交前获取 token 并传给后端，而非渲染控件；需确保前端正确注入 JS、显式调用 execute()、action 与后端一致，后端配置校验规则和阈值，并排查 CSP、本地域名、版本匹配问题。
直接上手就能用，但不配对、不埋点、不校验，grecaptcha.execute() 调了也白调——v3 的核心不是“显示控件”，而是“在提交前拿到 token 并传给后端”。
前端怎么注入 grecaptcha 并触发执行
v3 不渲染任何 UI 元素，只靠 JS 注入 + 手动调用。漏掉任一环节，控制台就会报 grecaptcha is not defined 或 token 为空。
-
renderField()（如{!! RecaptchaV3::field('login') !!}）会自动插入 Google 官方 JS（https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY），但它只负责加载，不自动执行 - 必须在表单提交前显式调用
grecaptcha.execute('YOUR_SITE_KEY', {action: 'login'})，且action名称要和后端校验时用的完全一致（大小写敏感） - JS 加载时机很重要：不能放在
顶部就调用；推荐把执行逻辑包在window.onload或表单submit事件里，确保grecaptcha已就绪 - 如果用了 Livewire，注意它会拦截原生 submit，得用
@this.call('submitWithRecaptcha')这类方式绕过，否则handle事件不触发
后端怎么验证 g-recaptcha-response 字段
Laravel 默认不识别这个字段，直接丢进 validate() 会报 Invalid captcha 却没提示，因为校验失败没绑定到 $errors。
- 规则必须写成
'g-recaptcha-response' => 'required|recaptcha'，不是recaptcha、captcha或其他别名 - 确保已发布配置：运行
php artisan vendor:publish --provider="JosiasMontag\RecaptchaV3\RecaptchaV3ServiceProvider"，生成config/recaptchav3.php -
.env中必须有RECAPTCHAV3_SITEKEY和RECAPTCHAV3_SECRET，且与前端execute()用的site_key一致 - v3 返回的是 score（0.0–1.0），默认阈值是 0.5；若需更严，修改配置里的
score_threshold，并在验证失败时手动加错误：$validator->errors()->add('g-recaptcha-response', '验证未通过');
CSP、本地开发、密钥匹配这三处最容易卡住
这三个点不排查完，前端看着有徽章、后端看着有请求，但就是过不了——而且没有任何明确报错。
- CSP 策略会拦截
https://www.google.com/recaptcha/域名下的 JS 和请求，临时关掉Content-Security-Policy头可快速验证是否为此问题 - localhost 开发时，Google 控制台注册站点必须明确添加
http://localhost和http://127.0.0.1（协议、端口都要对），否则返回invalid-input-secret或空 score - 前后端用的 reCAPTCHA 版本必须一致：配置文件里
version设为v3，前端 JS URL 里render=xxx，后端校验器也得是 v3 专用的（比如josiasmontag/laravel-recaptchav3，不是anhskohbo/no-captcha）
v3 的隐蔽性是一把双刃剑：用户无感，开发者也容易忽略 token 何时生成、何时发送、何时校验——最常出问题的不是代码写错，而是三个地方没对齐：前端 action 名、后端配置 score_threshold、Google 控制台注册域名。
