美洽域名白名单怎么设置？

要在美洽里允许某个站点加载客服小窗，需在控制台找到“域名/站点白名单”配置，把要允许的域名逐行添加并保存，然后在页面中加载美洽脚本时确保域名一致（注意去掉协议与末尾斜杠、区分www与非www），同时确认HTTPS、跨域与缓存问题已处理。若使用多环境（开发/测试/生产），把各环境域名都加入白名单；本地调试可临时加入localhost或127.0.0.1。如遇拒绝加载，查看浏览器控制台与美洽后台的报错提示，按域名格式、子域、端口和iframe策略逐项排查即可。

先把概念讲清楚：域名白名单是什么，为什么要设置？

把域名白名单想象成门卫名单。你的客服小窗脚本（或服务端接口）不想随便被任意网站调用，否则可能被滥用、盗链或泄露数据。白名单就是告诉美洽“只有这些列在名单上的网站，才被允许嵌入或调用我的客服功能”。

白名单的三个主要目的

• 安全控制：防止第三方站点未经授权载入你的客服资源或冒充你的客服界面。
• 流量与成本管理：限制访问来源可以避免非预期的调用，减少异常流量。
• 定位问题：明确允许的域名后，出问题时能更快判断是否是域名配置导致的加载失败。

在哪儿设置（一般流程，界面名称可能随版本变化）

美洽控制台的界面会迭代，但大体位置和步骤相对稳定。下面按“常见控制台路径”给出一般流程，操作时以你当前账号看到的菜单为准。

常见的操作路径（逐步）

• 登录美洽客服后台（企业账号）。
• 进入“设置”或“系统设置”。
• 找到“网站接入”、“渠道管理”或“客户端配置”等与嵌入式客服相关的栏目。
• 在该栏目下找到“域名白名单”、“允许的站点域名”或“接入域名”一项。
• 在输入框里按要求添加域名（通常一行一个），完成后点保存或确认。
• 回到你的前端页面，确保引入的美洽脚本域名与白名单中的域名一致，刷新页面测试。

如果找不到白名单配置项怎么办？

• 检查当前账号是否有管理员权限，部分设置只有管理员或拥有相应权限的子账号才能看到。
• 界面更新后，白名单可能移动到“安全设置”、“渠道设置”或“嵌入设置”下，多翻几层菜单。
• 联系美洽客户经理或工单支持，索取你当前版本控制台的说明。

域名到底怎么写？格式细节与常见错误

写域名是最容易出错的地方，尤其是初次配置时。下面把常见规则和坑点一条条列清楚。

基本格式建议

• 不要带协议：只写 domain.com 或 sub.domain.com，不要写 http:// 或 https://。
• 不要末尾斜杠：domain.com/ 会被视为不同字符串，建议去掉斜杠。
• 区分主域与子域：www.example.com 与 example.com 通常是不同条目，两个都写上更保险。
• 端口通常不需要写：若你的环境特殊（例如开发用 3000 端口），可以写成 example.com:3000，但多数情况下写域名即可。
• 通配符支持：不同版本可能支持 *.example.com 或 *.sub.example.com，需查看控制台提示；若不支持，逐个子域添加。

典型错误与排查方法

实操：逐步示例（假设控制台路径）

下面给出一套可以直接照着操作的步骤，读到哪儿就做哪儿，做完逐项检查。

步骤一：登录并定位设置

• 用企业管理员账号登录美洽后台。
• 在左侧菜单找到“设置”或“系统设置”。
• 在设置里找“网站接入/渠道管理/小程序与网站”等与接入相关的项。

步骤二：找到“域名白名单”输入框

• 通常会看到一个可编辑的文本区域，提示“一行一个域名”或类似文字。
• 如果看到“允许的域名”、“接入域名”，那就是它了。

步骤三：添加域名（示例）

假设你有三个环境：本地开发、测试域、生产域。你可以这样写：

• localhost
• 127.0.0.1
• test.example.com
• example.com
• www.example.com

添加完成后点击保存或确认。

步骤四：前端验证

• 清空浏览器缓存或在无痕模式下打开目标页面。
• 打开开发者工具查看控制台，关注与美洽相关的错误信息（域名允许/跨域/证书等）。
• 如果仍然看不到小窗，检查页面是否正确引入美洽脚本、脚本加载顺序，以及是否有 JS 报错阻断执行。

与 HTTPS、CORS、iframe 相关的注意事项

光把域名放到白名单里还不够，有时浏览器策略或服务器设置也会影响加载。

HTTPS 强制与证书

• 如果你站点启用了 HTTPS，确保美洽脚本通过 HTTPS 加载；混合内容会被浏览器阻止。
• 如果使用自签名证书或证书错误，浏览器可能阻止脚本或资源加载，尽量使用有效证书。

CORS / Referer / Origin

• 美洽的某些接口可能会校验 Referer 或 Origin，保证这些值和白名单一致。
• 在代理、CDN 或跳转时，Referer 可能被改变，要注意回源时的 header 设置。

iframe 嵌入场景

• 如果你把客服小窗放在 iframe 内，浏览器的 X-Frame-Options 或 CSP 可能阻止显示。需要确认父页面与 iframe 的 header 设置允许嵌入。
• 某些白名单校验会以最外层页面的域名为准，所以 iframe 内加载时要把最外层域名加入白名单。

多环境与自动化部署的实践建议

企业通常有开发、测试、预发、生产多个环境。管理白名单最好有规则，避免每次部署都手动修改控制台。

建议做法

• 在美洽后台列出所有环境域名：把 dev/test/pre/prod 的域名都加入，避免临时阻断。
• 对临时域名做命名规范：例如 dev.example.com、test.example.com，便于审计。
• 自动化提示：部署脚本可在上线说明中提示“如需接入美洽，请确认域名是否已添加到白名单”。可以通过工单或支持 API 询问美洽是否有批量接口（不同账号版本可能有差异）。
• 生产最严格，开发可灵活：生产环境只放必需域名，开发环境可以临时放通 localhost/127.0.0.1。

调试技巧：遇到加载失败时按步骤排查

调试不用慌，按下面的顺序把最常见的问题排掉就行。

排查清单（按顺序）

• 确认页面是否成功引用美洽提供的脚本（检查 Network 面板）。
• 查看控制台是否有“域名非法/域名未授权/不是允许的域名”等提示。
• 确认白名单里写的域名是否与页面地址严格一致（包括 www、子域、端口）。
• 如果用 CDN 或反向代理，确认回源后 Referer 没被篡改。
• 如果用 iframe，检查 X-Frame-Options 与 CSP。
• 尝试把目标域名临时加入白名单看是否问题消失，从而确定问题是否域名导致。
• 如仍然无解，截取控制台错误并联系美洽客服工单支持，附上报错信息和当前白名单截图。

样例：如何在白名单里记录不同场景的域名

下面给几个常见记录示例，方便复制粘贴模仿。

安全与合规：不要忽视的事项

域名白名单只是第一道防线。配合以下做法可以更安全：

• 定期审计白名单：移除不再使用的域名，特别是临时或测试域名。
• 权限控制：只有少数管理员能修改白名单，避免误操作或滥用。
• 监控异常调用：开启美洽的访问日志或告警，发现异常访问及时处理。
• API Key 与后台账号保护：如果接入中涉及服务端密钥，要按最小权限原则管理密钥。

最后一点小提示（一些开发者经常忽略）

很多时候问题不是“美洽不工作”，而是我们习惯性把两个看似相同的域名当成一回事：例如 example.com 与 example.com:8080、以及带有缓存的 CDN 域名。验证时试着把实际浏览器地址栏里的完整 host 与白名单做严格比对，省很多时间。哦，对了，如果你是在企业网络内（例如公司内网穿透或 VPN），记得也把实际看到的 host 加进去。

常见误区一览

• 误以为通配符万能：并不是所有控制台都支持 *.domain 的写法，遇到不支持得逐个写。
• 误以为添加一次就万事大吉：环境变动后要检查是否仍然匹配。
• 误把协议当作域名：写 http://example.com 往往会导致不匹配。

如果你按上面步骤操作：找对配置项、以正确格式添加域名、处理好 HTTPS 与跨域、检查 iframe 与缓存，通常就能解决绝大多数“加载失败”的问题。要是卡在某个环节，留个心眼把浏览器控制台的错误信息、当前白名单内容和你的页面地址一并准备好，联系美洽支持时会更快拿到帮助。好了，就先写到这儿，想到别的我再补上，做完操作顺利的话你就轻松了——我也能松口气了，嘿。