JSSDK在二级域名下配置，核心是搞定域名授权与跨域策略
JSSDK在二级域名下正确配置与使用的关键，在于将JSAPI安全域名、业务域名和服务器域名都精确指向你的二级域名，并确保页面协议（HTTPS）与SDK初始化参数完全匹配，否则会出现签名失败或接口无响应的典型问题。
很多开发者把主域名配置好了，以为二级域名自动继承，结果在wx.config阶段就报invalid signature，或者在调用分享、支付接口时毫无反应，这背后的坑，主要出在域名校验文件放置位置、JS接口安全域名列表的精确匹配，以及跨域Referer策略上,下面按实际排查顺序拆解。
JSSDK二级域名配置的核心障碍：域名校验文件与安全域名列表
域名校验文件必须放在二级域名的根目录，而非主站根目录
微信JS-SDK、百度地图JSSDK、支付宝JSAPI等主流SDK，都要求你在授权域名根目录下放置一个指定文件名的校验文件，这个文件是随机生成的，比如MP_verify_xxxx.txt。
行业共识认为，多数开发者踩坑的第一站就是文件位置，你在主域名example.com的根目录放了校验文件，然后在mp.example.com下调用SDK，平台校验时访问的是https://mp.example.com/MP_verify_xxxx.txt，发现文件不存在,直接拒绝授权。
正确做法是：
- 登录对应开放平台后台，找到“JS接口安全域名”设置项。
- 输入你的完整二级域名，例如
mp.example.com，不要带https://前缀,也不要带路径。 - 下载平台生成的校验文件，使用FTP或服务器面板，将该文件上传至二级域名绑定目录的根目录。
- 用浏览器直接访问
https://mp.example.com/MP_verify_xxxx.txt，确认能输出文件内容，再点击平台上的“保存并验证”。
安全域名列表的精确匹配规则
安全域名列表不支持通配符，你配置了example.com，并不意味着mp.example.com自动生效。每个二级域名都必须单独添加一次，如果业务涉及多个子域，比如mp.example.com和api.example.com，需要分别添加,并分别放置校验文件。
这里有个易被忽略的细节：部分平台的安全域名要求不带端口号，如果你的二级域名是通过mp.example.com:8080访问的，配置时依然只填写mp.example.com，但SDK初始化时，当前页面URL的端口必须与签名算法中使用的URL完全一致,否则签名校验失败。
二级域名jssdk跨域问题：Referer与Origin的实战处理
跨域请求的Referer白名单策略
当你的页面部署在mp.example.com，而SDK需要向api.example.com
发起Ajax请求时，会触发跨域，大多数JSSDK的跨域问题，并非平台限制，而是服务端未正确配置Referer白名单。
以微信JSSDK为例，它内部发起的请求会携带当前页面的Referer头，服务端在获取access_token或校验签名时，会比对Referer域名，如果服务端只允许example.com的Referer，来自mp.example.com的请求就会被拒绝。
解决路径如下：
- 登录服务端代码所在机器,找到鉴权接口拦截逻辑。
- 将Referer白名单数组从
["example.com"]扩展为["example.com", "mp.example.com"]。 - 如果使用Nginx做反向代理，在
server块中检查valid_referers配置,务必加上二级域名。
Cookie与Session的跨子域共享
二级域名下使用JSSDK，经常需要用户登录态，默认情况下，mp.example.com的Cookie不会发送给example.com，反之亦然，这会导致SDK内部请求获取不到用户身份,接口返回未登录错误。
行业共识认为，解决Cookie跨子域的标准方案是设置Domain属性，在服务端设置Cookie时，将Domain设为.example.com，这样所有子域都能共享，具体命令（以Node.js为例）：
res.setHeader('Set-Cookie', 'session_id=abc123; Path=/; Domain=.example.com; HttpOnly; Secure');
注意，Domain必须以点开头，并且不能包含端口，设置完成后，清空浏览器缓存，重新访问mp.example.com，在开发者工具Application面板中，确认Cookie的Domain列显示.example.com。
JSSDK二级域名配置的具体步骤：从初始化到签名验证
确认当前页面URL与签名URL完全一致
这是排查签名失败的最高频原因，JSSDK的签名算法是对当前网页的URL进行SHA-1哈希，但这里的“当前URL”是指调用wx.config时，location.href.split('#')[0]的值,即去掉hash部分。
在二级域名下，常见错误是页面通过http://mp.example.com访问，但签名时误用了https://mp.example.com，或者反向代理后，后端拿到的URL是内网地址，务必在页面中输出实际签名用的URL,与服务端日志比对。
推荐做法：在前端代码中,动态获取并传递URL：
const currentUrl = window.location.href.split('#')[0];
// 将currentUrl发送给后端换取签名
配置JS接口安全域名并验证
进入开放平台后台，找到“JS接口安全域名”一栏，点击修改，输入mp.example.com，保存后，平台会要求你点击验证按钮，此时平台会立即访问https://mp.example.com/MP_verify_xxxx.txt
，如果报错“文件不存在或无法访问”,优先检查：
- 二级域名是否绑定到了正确的服务器目录。
- 服务器防火墙是否屏蔽了平台爬虫的User-Agent。
- 文件是否被CDN缓存了旧内容,需要刷新CDN缓存。
服务端获取access_token并缓存
JSSDK的access_token获取接口，有每日调用次数限制（多数平台限制为2000次），二级域名环境下，必须做全局缓存，建议使用Redis或Memcached，将access_token缓存到过期前5分钟,避免频繁调用。
伪代码逻辑：
- 请求到达服务端，先从Redis查
wx_access_token。 - 命中则直接返回，未命中则调用平台接口获取,写入Redis并设置过期时间。
- 生成
jsapi_ticket时，同样走缓存逻辑，且jsapi_ticket的缓存逻辑与access_token一致。
二级域名JSSDK调试：高频报错与排查清单
invalid signature 签名错误
现象：页面加载后，调用wx.ready不执行，wx.error回调返回invalid signature。
排查顺序：
- 对比签名用的URL与页面实际URL，注意大小写、协议、端口。
- 检查服务端时间戳是否与当前时间相差超过5分钟，
timestamp参数必须是当前Unix时间戳秒数。 - 确认
nonceStr参数在签名算法中是否与前端传入的完全一致。 - 查看平台调试工具，手动输入URL和参数，模拟签名,比对结果。
config:fail, Error: 系统繁忙，请稍后重试
这个报错多数情况下是服务端获取jsapi_ticket失败，原因可能是access_token缓存失效，或者IP白名单限制，在二级域名场景下，如果服务器出口IP变了（比如切换了CDN回源）,需要去平台后台更新IP白名单。
the permission value is offline verifying
这个提示说明该JS接口未在安全域名列表内，确认你调用的接口（比如updateAppMessageShareData）是否需要在后台单独申请权限，部分高级接口，除了配置域名，还需要在“接口权限”页面单独开通。
二级域名JSSDK的安全与性能：多域名场景下的最佳实践
签名服务独立部署，避免主站逻辑耦合
如果你的主站和二级域名运行在不同服务器（比如主站是Java，二级域名是PHP），建议将签名服务独立成一个接口，专门处理签名生成，这样二级域名页面请求签名时，不用经过主站业务逻辑，响应速度更快,也避免了跨域Cookie问题。
接口设计建议：
- 接口地址：
https://mp.example.com/api/jssdk/sign - 请求参数：
url
- 返回数据：
appId、timestamp、nonceStr、signature
使用HTTPS并强制跳转
2026年的主流平台政策，均要求JSSDK必须在HTTPS协议下使用，如果二级域名仍用HTTP，SDK初始化会直接拒绝，在Nginx配置中,添加强制跳转：
server {
listen 80;
server_name mp.example.com;
return 301 https://$host$request_uri;
}
多域名场景的配置矩阵
如果你的业务涉及多个二级域名，建议维护一份配置矩阵表格,防止遗漏：
| 域名 | 校验文件位置 | 安全域名列表已添加 | 服务端Referer白名单 | HTTPS已启用 |
|---|---|---|---|---|
| example.com | 根目录 | 是 | 是 | 是 |
| mp.example.com | 根目录 | 是 | 是 | 是 |
| api.example.com | 不需要 | 是 | 是 | 是 |
业内专家指出，大部分线上故障源自配置矩阵中的“已添加”状态与实际后台不一致,比如后台被误删或权限变更。
JSSDK在二级域名的正确配置，本质上就是域名授权、文件放置、跨域策略、签名一致性这四个环节的闭环，把校验文件放到二级域名的根目录，把安全域名列表精确到子域，把服务端Referer白名单和Cookie域都扩展到.example.com，再确保签名URL与实际访问URL完全一致，整套流程就能跑通，遇到问题时，按上述排查清单逐项验证,比反复试错更高效。
Q&A：关于jssdk二级域名配置与使用的常见疑问
二级域名下JSSDK的域名校验文件，能否放在主域名的子目录里？
不能，校验文件必须放在二级域名自身对应的Web根目录下，平台校验时，是直接拼接域名和文件名进行访问，不会去主域名目录下寻找，校验mp.example.com，访问的地址是https://mp.example.com/MP_verify_xxxx.txt，如果该文件放在example.com/verify/目录下,平台无法找到。
二级域名使用JSSDK时，如果页面有单页应用路由（如Vue Router的history模式），签名URL应该取哪个？
签名URL必须取当前浏览器地址栏的完整URL，包括路径部分，但要去掉号及其后面的hash内容，对于history模式，路径会真实变化，所以每次路由切换后，如果SDK初始化需要重新执行，必须重新获取签名，对于hash模式，location.href.split('#')[0]的值始终是初始加载的URL，因此只需在页面首次加载时签名一次,后续hash变化不影响签名有效性。