JS接口安全域名配置的核心答案只有一句话：它只校验前端JS-SDK调用时的Referer来源，与服务器端请求无关，配置时必须使用不带协议头且与页面URL完全一致的域名。
很多开发者第一次接触微信JS-SDK时，都卡在安全域名配置这一关，明明代码逻辑没问题，但config接口一直报invalid url domain，或者调试时好端端的，一上线就失效，这篇文章把配置原理、操作步骤、高频踩坑点一次说透。
先弄懂JS接口安全域名的本质
微信公众平台的JS-SDK（比如分享、支付、扫一扫）会校验当前页面所在域名是否在白名单内,这个白名单就是JS接口安全域名。
业内专家指出，这项机制是防CSRF攻击的轻量级方案，它不校验IP、不校验路径、不校验端口，只校验域名主体（主域名+完整子域）。
JS接口安全域名和服务器域名的区别
这是新手最容易混淆的地方，两个概念看似差不多，实际指向完全不同的校验层,对比看更清楚。
| 对比维度 | JS接口安全域名 | 服务器域名 |
|---|---|---|
| 配置位置 | 公众号后台 -> 设置与开发 -> 安全中心 | 小程序后台 -> 开发管理 -> 开发设置 -> 服务器域名 |
| 适用对象 | 公众号H5页面调用JS-SDK | 小程序request/uploadFile等网络请求 |
| 校验方式 | 浏览器自动带上的Referer字段 | 服务器端校验的请求来源 |
| 是否带协议头 | 禁止带 https:// |
必须带 https:// |
| 生效时间 | 配置后约5分钟生效 | 配置后立即生效 |
| 常见报错 | invalid url domain |
url not in domain list |
所以当你在公众号H5里调JSSDK时，如果收到invalid url domain，去检查JS接口安全域名，如果你在小程序里发请求报url not in domain list,去检查服务器域名。
很多人问“js接口安全域名设置失败怎么回事”，十有八九是把这两者搞混了，公众号后台根本没有“服务器域名”这个配置项，小程序后台也没有“JS接口安全域名”这一栏。
JS接口安全域名正确设置流程
假设你的业务需要一个公众号H5页面，用户在这个页面里调用微信分享和微信支付，以下操作路径是微信官方文档推荐的,每一步都有明确入口。
准备域名并完成ICP备案
域名必须完成ICP备案，且在微信后台通过校验，备案主体与公众号主体不一致时，需要在后台上传相关授权证明，这个审核周期通常是1-3个工作日。
需要注意的是，不能使用IP地址、localhost或带端口的域名,微信要求域名必须为合法注册的顶级域名或二级域名。
登录公众平台后台操作
- 打开浏览器，访问
mp.weixin.qq.com。 - 扫码登录公众号管理员账号。
- 在左侧菜单栏找到设置与开发 -> 安全中心。
- 点击JS接口安全域名右侧的“修改”按钮。
- 在弹窗中输入你的域名，规则是：
- 不带
http://或https://前缀。 - 不带路径，例如
https://example.com/user/home是错误的写法。 - 不带端口号。
- 只能填写一个完整域名，如
wx.example.com。
- 不带
- 点击保存，系统会提示需要下载一个校验文件（
MP_verify_xxxx.txt）。
放置校验文件
这一步的操作是很多人忽略或操作错误的。
- 将下载的校验文件用代码编辑器打开,里面的内容是一串随机字符。
- 将文件原封不动地放在你填写的域名根目录下。
- 例如你填写的域名是
wx.example.com，那么访问https://wx.example.com/MP_verify_xxxx.txt时要能直接看到那串字符。 - 不能用框架路由拦截这个文件，比如你用Vue或React+history模式，如果用通配符劫持了所有路径，校验文件会仍返回HTML而非文本字符，此时请改用hash路由，或者在后端Nginx/云服务器配置中放行该文件扩展名。
校验通过后，域名配置成功，如果你希望在同一个公众号下支持多个H5应用，可以添加最多20个不同的域名,每个域名需独立校验。
避免JS接口安全域名配置常见坑
这类问题在开发者社区里讨论很热烈,以下场景是复现率最高的几个坑。
坑一：本地调试时的域名魔咒
在本地跑项目时，地址通常是http://localhost:8080，这个地址一定不在安全域名列表里，有几种解决方案,按推荐程度排列：
- 不用本地地址测JSSDK，直接把代码部署到测试环境（测试环境域名已配置进安全域名）。
- 使用内网穿透工具（如natapp、cpolar等），将本地端口映射到一个已备案且已配置的域名上,这个方案适合快速调样式。
- 修改本机hosts文件，将已配置的域名映射到
0.0.1,注意路径权限问题。
如果你已经扫了码，但提示config:fail，先检查网页当前的URL域名是否和后台一字不差，二级域名a.example.com和b.example.com是不同的。
坑二：域名填成了根域名但页面在子域名下
这是最隐蔽的坑，后台填的是example.com（根域名），但页面实际链接是shop.example.com，浏览器发出的Referer是https://shop.example.com/，微信后台比对发现前缀不一致,直接会判定失败。
正确做法是填写页面实际所在域的完整域名，如果你页面分布在多个子域,请全部添加到列表。
坑三：为了配置安全域名而配置假页面
有的开发者为图省事，把校验文件放在了根域名下，但页面实际运行在子域名，校验通过了，但JSSDK照样报错，因为微信校验文件验证的是域名所有权，但JSSDK运行时校验的是页面Referer，二者是两套独立机制，校验文件通过不等于页面域名在名单中。
坑四：HTTPS证书问题导致安全域名失效
微信明文要求所有JSSDK页面必须是HTTPS，如果你配置了https://wx.example.com，但该域名的SSL证书过期或无效,微信会拒绝加载JSSDK并报错。
自查方案是：进入控制台Network面板，看https://res.wx.qq.com/open/js/jweixin-1.6.0.js这个脚本是否请求成功，如果该脚本加载失败,大概率是证书信任链问题。
坑五：切换公众号环境时的配置残留
有些开发者同时维护测试号和正式号，测试号后台配置了test.example.com，正式号后台配置了www.example.com。
如果你在测试环境扫了测试号的二维码、在正式环境扫了正式号的二维码，但前端代码中的appId写死成了某一个，就会出现“我后台配置得好好的，为什么一直报签名错误”，排查时记得先核对当前页面注入的appId到底是哪一个。
配置后的验证步骤与调试技巧
配置完成后，别急着关后台，按以下顺序做一次完整性验证,能省掉很多后续排查时间。
- 确认配置已生效：让页面在微信内置浏览器中打开，点击右上角“...”菜单，选择“复制链接”,确认链接域名和后台配置完全一致。
- 检查签名算法：在调用
wx.config之前，后端需要用你填写的域名生成signature，前端收到的signature要和后端用同样算法（SHA1）比对，可以在控制台输入wx.config传入的参数对象，手动核对nonceStr、timestamp、url是否和后端参与签名的值完全一致。 - 利用debug模式：在调用
wx.config时传入debug: true，微信会在成功或失败时弹出提示框，上面直接显示错误码和原因，这个功能在正式环境会弹窗影响体验,记得上线前去掉。 - 验证分享功能：如果配置了
wx.updateAppMessageShareData，在ios和安卓两个端各测一次，iOS对url大小写敏感，Page和page视为不同路径。
据统计，大部分invalid signature错误都源于前端传到后端的url带了哈希路由部分，而后端签名时又把它去掉了。参与签名的URL必须是当前页面URL去除及其后面部分后的完整地址,且保留之前的字母大小写原样。
JS接口安全域名相关问题解答
问：js接口安全域名配置错误最常见的原因是什么？
抛开代码逻辑不谈，纯配置层面的高频错误有两个。第一个是填写了带https://前缀的完整URL，微信后台直接报“域名格式错误”。第二个是域名末尾带了斜杠，比如example.com/，这样也会被判定为非法格式，另外就是页面实际域名与配置的域名不匹配,比如页面用IP访问或临时域名访问。
问：js接口安全域名和request合法域名必须一样吗？
不需要一样，两者没有强制关联，JSSDK的安全域名是给H5页面加载微信原生SDK用的，request合法域名是小程序后端请求白名单，如果一个项目既有公众号H5又有小程序，两个配置项可以完全不同，但行业共识认为，为了统一维护和避免子域过多导致证书管理混乱，建议在条件允许的情况下使用同一个主域名下的不同子域，比如h5.example.com和api.example.com，这样在排查问题时不容易搞混域名归属，需要注意的是，小程序的request合法域名要求必须校验HTTPS证书，而JS接口安全域名本身就是HTTPS强制要求,两者在这点上是一致的。