opencms 集成 recaptcha v2 时页面仅显示空白区域，常见原因是服务器 content security policy（csp）阻止了 google 外部脚本加载，需检查浏览器控制台网络请求与 csp 响应头并调整策略。
在 OpenCMS 项目中集成 reCAPTCHA v2 时，即使正确引入了官方脚本和容器元素，仍可能出现 <div class="g-recaptcha"> 渲染为空白的情况。这并非 OpenCMS 特有缺陷，而多由前端安全策略或资源加载限制导致。以下为系统性排查与解决方案：
✅ 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 模式，避免依赖自动初始化时机：
<!-- 在 <head> 或页面底部引入（带回调参数） -->
<script src="https://www.google.com/recaptcha/api.js?onload=renderReCaptcha&render=explicit" async defer></script>
<!-- 表单中的容器 -->
<div id="recaptcha-container"></div>
<!-- 初始化脚本（确保 DOM 加载完成） -->
<script>
let recaptchaWidget;
function renderReCaptcha() {
if (typeof grecaptcha !== 'undefined') {
recaptchaWidget = grecaptcha.render('recaptcha-container', {
'sitekey': 'your_site_key_here',
'callback': function(token) {
console.log('reCAPTCHA token:', token);
// 提交表单前可校验 token
}
});
}
}
// 兼容 DOM 加载时机（推荐）
document.addEventListener('DOMContentLoaded', function() {
if (typeof grecaptcha === 'undefined') {
console.warn('reCAPTCHA API not loaded');
}
});
</script>✅ 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）有特殊验证规则。
