js安全域名

JS安全域名是微信生态中调用JS-SDK接口的域名白名单，只有配置在后台且通过校验的域名才能正常使用分享、支付、扫码等原生能力。配置不成功通常不是代码问题，而是域名规则没吃透或者校验文件位置放错了。

js安全域名是什么：前端开发者必须理解的信任边界

从技术本质上看,JS安全域名是微信公众平台为网页开发者设立的一道隔离墙，你的页面在浏览器里运行，微信无法判断这段代码是来自你的服务器还是被人恶意复制，安全域名的存在，就是告诉微信服务器：只有来自这些域名的请求，才有资格调用JS-SDK的能力。

业内专家指出,这套机制和OAuth授权回调域名的逻辑类似，都遵循”先验证归属、再开放能力”的原则。

JS接口安全域名的三个硬性规则

配置JS安全域名时,下面三条规则是踩坑率最高的：

• 不能带协议头：https:// 需要去掉，后台只需要填 example.com，填了协议头直接校验失败
• 不能带路径：example.com/page 这种写法不符合规范，只保留到一级或二级域名即可
• 域名必须备案：且备案主体要与公众号主体一致，个人公众号只能用个人备案域名，企业公众号同理

很多开发者习惯性地复制浏览器地址栏里的完整URL,结果就是反复提示”校验失败”，这不是代码出了bug，而是格式没按规范来。

验证文件到底该放在哪里

配置页面会让你下载一个 MP_verify_xxxx.txt 的校验文件，这个文件必须放在域名根目录，不是子目录，不是 /static 文件夹，就是根目录。

假设你要配置的域名是 js.example.com，那么校验文件需要能通过以下地址直接访问到：

http://js.example.com/MP_verify_xxxx.txt

在浏览器里能打开看到一串验证码,才算通过第一步，腾讯的验证机器人会模拟这个访问行为，如果放错位置或者返回404，配置就不可能成功。

js安全域名怎么设置：公众号后台的完整操作路径

整个配置过程大约需要五分钟,但前提是准备工作做到位，先确认两件事：域名已完成ICP备案，且备案主体与公众号主体一致，这两个条件不满足，后面的所有操作都是白费功夫。

后台操作四步走

第一步,登录微信公众平台，在左侧菜单找到【设置与开发】>【公众号设置】>【功能设置】。

第二步,找到”JS接口安全域名”这一栏，点击”下载校验文件”，文件是一个txt文档，下载后不要修改任何内容。

第三步,通过FTP、宝塔面板或SSH工具，将校验文件上传到域名根目录，上传完成后，先用浏览器访问一次，确认能正常显示验证码内容。

第四步,回到后台输入框，填写不带 http:// 和 https:// 的域名，点击保存，微信会自动跳转到校验文件进行验证，验证通过后域名即绑定成功。

提示：如果提示”校验文件访问失败”，优先检查是不是开了HTTPS强制跳转，验证机器人可能无法正确处理301跳转逻辑。

绑定几个域名最合适

微信公众平台最多允许绑定三个JS安全域名,对大多数业务来说，一个主域名就够了，不需要把三个配额全部用完。

常见的使用场景分配建议：

如果你名下有好几个子域名都在调JS-SDK，可以考虑统一收敛到一个主域名下，用路径区分业务模块，这样还能少维护一份校验文件。

网页授权域名和js安全域名有什么区别：别再把两者搞混

这是一个被反复问起的问题,很多人发现后台同时有”网页授权域名”和”JS接口安全域名”两个配置项，不清楚分别该填什么。

两者都做域名校验,但服务的接口完全不同：

• 网页授权域名：管的是OAuth2.0静默授权和用户信息获取，也就是 snsapi_base 和 snsapi_userinfo 这两个scope的跳转回调
• JS安全域名：管的是 wx.config 注入的JS-SDK接口调用，wx.shareTimeline、wx.scanQRCode、wx.chooseWXPay

一个典型的场景是：用户在微信里打开页面，通过网页授权拿到了openid，同时页面上要调用扫一扫功能，这种情况下，两个域名池里都需要配好对应的域名，缺一个都会报错。

网页授权域名与js安全域名的配置差异

网页授权域名的配置规则相对宽松一些,可以不校验文件，但要求回调域名和配置域名完全一致，JS安全域名则是必须校验文件，两者的生效时间也有区别：网页授权域名通常在几分钟内生效，JS安全域名偶尔会有十分钟左右的缓存延迟。

如果你的项目同时用到授权和JS-SDK，建议一次性把两个域名都配上，避免上线后临时补配置还要等缓存刷新。

js安全域名配置报错排查：从现象反推原因

实际开发中会遇到各式各样的报错信息,但归纳下来，九成以上的问题都出在下面几个环节。

签名失败 invalid signature

这个报错指向的是后端签名接口,JS-SDK要求后端用 noncestr、timestamp、url、jsapi_ticket 四个参数生成签名，其中任何一项对不上都会报这个错。

前端排查步骤：

• 确认 wx.config 里的 jsApiList 数组里包含了你正在调用的接口名
• 确认签名用的URL是当前页面的完整URL，去掉 号后面的部分
• 确认后端获取 jsapi_ticket 时用的access_token没有过期

多数情况下问题出在URL带上hash值导致签名串不匹配。

返回码提示 config:fail

返回码 config:fail 表示 wx.config 配置阶段就失败了，先看是不是JS安全域名没配或者配了还没生效，再排查 jsapi_ticket 是否由后端通过 https 协议获取，微信官方要求所有JS-SDK接口必须走HTTPS，如果你的页面是HTTP环境，直接调用会全部失败。

配置成功但个别接口不可用

这种情况通常是权限问题,部分接口有单独的开放条件，比如微信支付需要先开通商户号，微信扫一扫在未认证的订阅号里不可用。不是所有接口都对所有公众号开放，能力范围和公众号类型直接挂钩。

网站js安全域名配置的最佳实践与避坑建议

结合多年来的实践经验,这里整理几条值得注意的事项，帮你在配置阶段就规避掉大部分问题。

开发环境与生产环境的域名策略

开发阶段不建议直接占用三个正式配额,可以在本机绑定 wechat.test.com 这类测试域名，或者用内网穿透工具映射到本地，等测试通过后，再释放配额给生产环境域名。

团队协作时,建议用相同的校验文件部署到所有环境，微信允许同一个校验文件同时配置在多个域名上，这样可以避免每个环境生成独立文件造成管理混乱。

后续维护的几个操作习惯

• 每次修改域名配置后,在真机微信里清掉缓存再测试，开发者工具的缓存有时会干扰验证结果
• 定期检查公众号后台的”接口权限”页面，确认JS-SDK能力没有被官方降级
• 如果域名到期或备案被注销,及时在后台删除对应配置，避免影响其他域名的正常使用

微信的规则会不定期调整,每次调整后后台都会有公告通知，做线上业务的开发者，每隔一两个月去后台翻翻更新记录，这个习惯能省去不少排查问题的时间。

js安全域名和ip白名单怎么做选择

很多开发者会问,既然IP白名单也能限制调用来源，为什么还要配JS安全域名？两者的防护维度完全不同。IP白名单是给服务器端API调用用的，JS安全域名是给浏览器端页面用的

。

服务器端的接口调用,微信看到的调用方IP是你的服务器出口IP，可以用白名单固定住，但浏览器端的页面请求，IP是用户的，不可能把所有用户IP都加进白名单，所以JS安全域名就成了唯一合理的前端管控手段。

从安全层级上看,两者的关系是互补的：后端接口靠IP白名单防，前端页面靠JS安全域名防，不少公司会同时配置两者，形成双层防护，单靠JS安全域名并不能阻止别人抓取你的页面代码后自己伪造请求，因为请求到了服务器端还是需要IP白名单放行。

js安全域名在哪些场景下必须配置

如果你的页面只做静态展示,完全没有调用微信原生能力的需求，那确实不需要配置，但下面这些场景，不配就寸步难行：

• H5页面需要唤起微信扫一扫识别二维码
• 网页内需要调起微信支付拉起收银台
• 单页应用需要自定义分享卡片到朋友圈或会话
• 页面需要获取当前位置（wx.getLocation）
• 需要把图片保存到相册（wx.saveImageToPhotosAlbum）

这些能力都依赖JS-SDK注入，没有安全域名的授权，wx.config 第一步就过不去，后面所有的接口调用都会返回 permission denied。

部分企业在做活动落地页时,会出现有赞、微盟等第三方平台域名下的页面也需要调微信能力的情况，这时需要把第三方平台分配的独立域名也加入安全域名列表，所以三个配额有时候真的不太够用，申请时要有取舍，优先给线上正在跑的页面用。

常见问题速答

问：js安全域名和ip白名单有什么区别？
IP白名单限制的是服务器端API调用的来源IP，JS安全域名限制的是浏览器端页面的来源域名，前者管后端，后者管前端，两者可以同时配置且互不干扰，公众号后台的”基本配置”里设置IP白名单，只有白名单内的服务器IP才能拿access_token调接口。

问：JS接口安全域名能绑定几个，个人订阅号可以配置吗？
目前微信公众平台允许绑定最多3个JS接口安全域名，个人订阅号可以配置，但需要域名完成ICP备案且备案主体与注册主体一致，未认证的个人订阅号会受限，部分高级接口不可用，这一点需要一个账号一个账号地确认具体权限范围。

问：改了js安全域名之后多久生效，需要重新发版吗？
多数情况下保存后即刻生效，但偶尔会碰到缓存延迟，最长十分钟左右，如果测试中发现配置无误却仍然调用失败，等一会儿再重新打开页面试试，通常不需要重新发版，前端代码里的 wx.config 是运行时动态拉取的，不存在构建期写死域名的问题。