opencms 集成 recaptcha v2 时页面仅显示空白区域，常见原因是服务器 content security policy（csp）阻止了 google 外部脚本加载，需检查浏览器控制台网络请求与 csp 响应头并调整策略。
在 Opencms 项目中集成 reCAPTCHA v2 时，即使正确引入了官方脚本和容器元素，仍可能出现
✅ 1. 首要排查：Content Security Policy（CSP）拦截
reCAPTCHA v2 依赖从 https://www.google.com/recaptcha/ 加载 js 脚本及后续 iframe 内容。若 Web 服务器（如 apache）或反向代理（如 nginx）配置了严格的 CSP 响应头，将直接阻止外部脚本执行。
验证方法：
- 打开浏览器开发者工具 → Network 标签页
- 刷新页面，筛选 recaptcha/api.js 请求
- 查看该请求的 Status 是否为 (blocked:csp) 或响应头中是否包含 Content-Security-Policy
- 同时切换到 console，搜索关键词 Content Security Policy，常见报错示例：
Refused to load the script 'https://www.google.com/recaptcha/api.js' because it violates the following Content Security Policy directive: "script-src 'self'".
修复方案（以 Apache 为例）：
在虚拟主机或 .htaccess 中补充允许 Google reCAPTCHA 的 CSP 策略：
Header always set Content-Security-Policy "script-src 'self' https://www.google.com https://www.gstatic.com; frame-src 'self' https://www.google.com; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com;"⚠️ 注意：’unsafe-inline’ 仅在必要时添加（如内联样式），生产环境建议使用 nonce 或 hash；frame-src 必须显式声明 https://www.google.com，否则 reCAPTCHA iframe 将被拒绝渲染。
✅ 2. 确保 dom 就绪后再初始化（显式渲染）
若 CSP 已放行但仍无响应，建议改用 explicit rendering 模式，避免依赖自动初始化时机：
✅ 3. 其他关键检查项
- 网络连通性：确认 OpenCMS 所在 VM 可访问 https://www.google.com/recaptcha/api.js（可通过 curl -I https://www.google.com/recaptcha/api.js 测试）；
- HTTPS 一致性：若站点为 HTTPS，务必使用 https:// 协议引入脚本，避免混合内容警告；
- Site Key 正确性：确保 data-sitekey 或 render() 中传入的是 v2 类型的 site key（非 v3），且域名已在 Google reCAPTCHA 控制台 正确配置；
- OpenCMS 缓存机制：清除 OpenCMS 的模板缓存（/system/workplace/cache/）及浏览器缓存，避免旧版 html 被缓存。
✅ 总结
reCAPTCHA 在 OpenCMS 中“不显示”的核心原因，90% 以上源于 CSP 策略限制。优先通过浏览器 Network/Console 定位拦截行为，再针对性放宽 script-src 和 frame-src；辅以显式渲染模式提升兼容性。完成配置后，务必在真实环境（非 localhost）测试，因 Google reCAPTCHA 对本地开发域名（如 127.0.0.1、localhost）有特殊验证规则。