opencms 集成 recaptcha v2 时页面仅显示空白区域，常见原因是服务器 content security policy（csp）阻止了 google 外部脚本加载，需检查浏览器控制台网络请求与 csp 响应头并调整策略。
在 OpenCMS 项目中集成 reCAPTCHA v2 是一项常见但易出错的任务，尤其当环境涉及多 VM 架构（如 CMS 与应用服务器分离）时。你已正确引入官方 SDK 脚本和容器 DOM 元素：
<script src="https://www.google.com/recaptcha/api.js" async defer></script> <div class="g-recaptcha" data-sitekey="your_site_key_here"></div>
但页面仅渲染出空白 <div>，说明 reCAPTCHA 初始化失败——这几乎从不源于 OpenCMS 自身限制，而多由基础设施级安全策略拦截导致。
? 核心排查点：Content Security Policy（CSP）
现代 Web 服务器（如 Apache/Nginx）或反向代理常配置 Content-Security-Policy HTTP 响应头，严格限制外部资源加载。若策略中未显式允许 https://www.google.com 的脚本（script-src）及连接（connect-src），reCAPTCHA 的 JS 文件将被浏览器静默拒绝，且控制台 Network 面板会显示 “Blocked by CSP” 状态（状态码为 (blocked)）。
✅ 快速验证步骤：
- 打开浏览器开发者工具 → 切换至 Network 标签；
- 刷新页面，筛选 api.js 或 recaptcha 请求；
- 若该请求状态为 (blocked) 或无响应，右键 → Copy → Copy response headers，搜索 content-security-policy 字段；
- 检查其中 script-src 是否包含 'self' https://www.google.com，frame-src（v2 使用 iframe）是否包含 https://www.google.com（v2 必需！），以及 connect-src 是否允许 https://www.google.com（用于验证请求）。
? 解决方案（以 Apache 为例）
在虚拟主机或 .htaccess 中添加/修正 CSP 头（注意：frame-src 在较新 CSP 版本中已替代 child-src，但 reCAPTCHA v2 仍依赖 frame-src）：
# Apache 配置示例（需启用 mod_headers） Header always set Content-Security-Policy "default-src 'self'; \ script-src 'self' https://www.google.com https://www.gstatic.com; \ style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; \ frame-src 'self' https://www.google.com https://recaptcha.google.com; \ connect-src 'self' https://www.google.com; \ font-src 'self' https://fonts.gstatic.com; \ img-src 'self' data: https:;"
⚠️ 注意事项：
- https://recaptcha.google.com 是 v2 验证 iframe 的实际来源，必须加入 frame-src（遗漏此条是空白 captcha 的最常见原因）；
- https://www.gstatic.com 是 reCAPTCHA 所需字体与静态资源的域名，缺失会导致图标/样式异常；
- 若使用 'unsafe-inline' 存在风险，建议改用 nonce 或哈希值，但调试阶段可临时放宽；
- 修改后务必重启 Apache 并清除浏览器缓存（CSP 缓存较顽固）。
✅ 补充验证技巧
-
在浏览器 Console 中手动执行：
typeof grecaptcha !== 'undefined' && grecaptcha.render
若返回 undefined，说明 SDK 未加载；若返回函数但未渲染，可能是 data-sitekey 错误或 DOM 尚未就绪（建议将 g-recaptcha 放在 </body> 前，或用 onload 回调显式初始化）。
-
启用 reCAPTCHA 调试模式（仅限测试环境）：
<script src="https://www.google.com/recaptcha/api.js?render=your_site_key&debug=1" async defer></script>
控制台将输出详细加载日志。
? 总结
reCAPTCHA v2 在 OpenCMS 中“不显示”，本质是前端资源加载被阻断，而非模板或 CMS 逻辑问题。优先通过浏览器 Network 面板确认 CSP 拦截行为，针对性放宽 script-src、frame-src 和 connect-src 策略，并确保域名拼写精确（如 recaptcha.google.com ≠ www.google.com）。完成配置后，建议使用 Google CSP Evaluator 工具校验策略安全性，兼顾功能与防护。
