微信公众号JS接口安全域名配置步骤及校验文件上传指南
详细介绍微信公众号JS接口安全域名的配置前置条件、MP_verify校验文件上传至服务器根目录的方法、Nginx与单页应用放行示例,以及保存失败和invalid url domain排查指南。
在微信内打开的网页如果需要调用分享、扫一扫、获取地理位置或拍照上传等微信 JS-SDK 能力,必须先把网页所在域名加入微信公众号后台的“JS接口安全域名”白名单。整个配置过程分为三步:在公众号后台下载 MP_verify_*.txt 校验文件、将文件放到目标域名的 Web 根目录使其可通过公网直接访问、回到后台填写纯域名并保存。
一、配置前的准备与限制条件
在进入后台操作之前,先核对账号权限、域名状态和服务器部署条件,可以避免配置到一半因为资质或环境不满足而被卡住。
- 公众号账号权限:只有具备 JS-SDK 使用权限的公众号(通常为已完成微信认证的服务号或订阅号)才能配置正式的 JS 接口安全域名。个人主体或未认证账号在后台可能看不到对应设置项,或仅开放有限接口;若当前处于本地或测试联调阶段,可在微信公众平台接口测试号管理页面使用测试号提供的安全域名入口。
- 域名已完成 ICP 备案:在境内提供服务的主体绑定安全域名时,域名必须已在工信部完成 ICP 备案,且填写的必须是正式域名,不能使用 IP 地址(如
120.78.x.x)或本地地址(localhost)。 - 使用默认标准端口:安全域名默认通过 HTTP(80 端口)或 HTTPS(443 端口)对外提供服务,配置框内不能携带非标准端口号(如
:8080)。 - 具备域名根目录的控制权:微信服务器在保存配置时会实时校验域名归属权,因此需要你有权向该域名对应服务器、负载均衡、CDN 或对象存储的根路径写入文本文件,并确保该文件不被登录鉴权或路由规则拦截。
- 留意数量上限与修改次数限制:公众号后台对可绑定的安全域名总数以及自然月内允许修改的次数均设有上限,具体可用配额和本月剩余修改次数以设置弹窗页面实时显示的提示为准。
二、在公众号后台获取校验文件
微信公众平台通过校验文件确认“你确实拥有并能够管理该域名”,从而防止他人把无关域名填入白名单后冒用 JS-SDK 接口权限。
- 使用管理员或有权限的运营者微信号,登录微信公众平台网页端(
mp.weixin.qq.com)。 - 在左侧导航栏展开 设置与开发,点击进入 公众号设置,然后切换到顶部的 功能设置 标签页(若后续平台微调菜单名称,可在“公众号设置”相关分页中查找“JS接口安全域名”)。
- 找到 JS接口安全域名 一栏,点击右侧的 设置 按钮,打开域名配置弹窗。
- 在弹窗提示文字中找到校验文件下载链接,点击下载该文件。文件名通常采用
MP_verify_随机字符串.txt的格式,例如MP_verify_a1b2c3d4e5f6g7h8.txt,文件内容是一串对应的纯文本验证码。
三、将校验文件上传到服务器根目录
上传校验文件最核心的要求是:文件必须位于待配置域名的根路径下。假设你要配置的安全域名是 m.example.com,校验文件名为 MP_verify_a1b2c3d4e5f6g7h8.txt,那么微信服务器点击保存后会直接请求 http://m.example.com/MP_verify_a1b2c3d4e5f6g7h8.txt(或对应的 HTTPS 地址),并期待直接拿到纯文本验证码。
如果你的前端页面实际部署在子目录(例如 https://m.example.com/h5/),校验文件仍然必须放在域名根路径 /MP_verify_a1b2c3d4e5f6g7h8.txt,不能放进 /h5/ 目录里,因为微信服务端只会固定从域名根目录读取文件。
1. 常见服务器与托管环境的上传方式
不同建站或部署架构下,根目录的位置和处理方式略有差异,按实际环境选择对应做法即可。
- 传统服务器或虚拟主机(如宝塔、cPanel、Apache):通过 FTP/SFTP 或控制面板文件管理器,找到站点配置绑定的根目录(例如
/var/www/html/或/www/wwwroot/m.example.com/),直接将MP_verify_a1b2c3d4e5f6g7h8.txt上传到该目录。若 Apache 站点配置了统一伪静态重写规则(如 ThinkPHP、WordPress 的.htaccess),需确认存在放行真实文件的条件(即RewriteCond %{REQUEST_FILENAME} !-f)。 - Nginx 反向代理或前后端分离(Vue / React History 模式):单页应用常把所有未匹配路径回退到
index.html,这会导致请求校验文件时返回网页 HTML 而不是 txt 内容;或者 Nginx 将全部流量proxy_pass转发给后端接口而未托管静态文件。此时应在对应server块中增加一条精确匹配规则,优先把校验文件交由静态目录返回(或直接由 Nginx 输出文本)。
示例:Nginx 配置精确放行校验文件(仅作配置参考,路径与文件名请替换为实际值)
server {
listen 80;
listen 443 ssl;
server_name m.example.com;
root /var/www/h5/dist;
index index.html;
# 精确匹配校验文件,优先于单页应用回退或后端代理规则
location = /MP_verify_a1b2c3d4e5f6g7h8.txt {
default_type text/plain;
try_files $uri =404;
}
location / {
try_files $uri $uri/ /index.html;
}
}
如果后端服务临时不便改静态目录,也可以在对应的 Nginx server 块中直接返回校验文本(注意把字符串替换为下载文件内的真实文本):
location = /MP_verify_a1b2c3d4e5f6g7h8.txt {
default_type text/plain;
return 200 'a1b2c3d4e5f6g7h8';
}
- 前端静态打包项目(Vite / Webpack 等):如果网站直接由前端构建产物托管在域名根目录,可将校验文件放入项目的
public/(或旧版框架的static/)目录,重新构建部署后,该文件会自动输出到产物根目录。 - 对象存储(OSS / COS)或 CDN 托管:若域名直接指向对象存储桶,需将校验文件上传至存储桶的最顶层根目录(无任何文件夹前缀),并将文件读写权限设为公共读;若开启了 CDN 缓存或自定义错误页回源规则,确认刷新缓存且不会对
.txt请求返回自定义页面。
2. 上传后的公网访问自测
上传完成后,不要只凭本地文件存在就去点保存,先在浏览器无痕窗口打开 https://m.example.com/MP_verify_a1b2c3d4e5f6g7h8.txt(若站点未开启 HTTPS 则测试 http://),确认页面上直接显示出校验字符串,且没有触发登录跳转或下载弹窗。
更稳妥的方式是在终端使用 curl -i 检查真实状态码和响应头,避免浏览器缓存掩盖问题:
自测命令(在任意可访问公网的终端执行)
curl -i https://m.example.com/MP_verify_a1b2c3d4e5f6g7h8.txt
示例输出(预期结果示意)
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 16
a1b2c3d4e5f6g7h8
如果看到的是 301、302(例如跳往登录页或带 www 的另一个域名)、403、404,或者返回的响应体是 <!DOCTYPE html>... 网页代码,都说明尚未部署到位,需要先修复再回公众号后台操作。
四、在公众号后台填写并保存域名
确认公网能够稳定返回状态码 200 与纯文本校验码后,回到微信公众号后台的“JS接口安全域名”设置弹窗,在输入框中填写域名并点击保存。
填写时严格遵守纯域名格式:只写主机名本身,不能包含 http://、https://,也不能带末尾斜杠 /、子目录路径或端口号。例如页面地址是 https://m.example.com/act/2026/index.html,配置框内只需填写 m.example.com。
如果同时有多个子域名(例如 m.example.com 和 shop.example.com)都需要调用 JS-SDK,注意核对设置弹窗的说明:当主域名和子域名指向不同服务器或存在严格主机匹配需求时,建议将实际访问页面的精确域名逐一填入并分别上传校验文件(如果多个域名绑定了同一台服务器根目录,使用同一份校验文件即可)。
点击“保存”后,如果弹窗正常关闭且列表中展示出刚填写的域名,说明微信服务器已成功抓取并核验了根目录下的校验文件。建议保留服务器上的 MP_verify_*.txt 文件不要急于删除,以免后续新增其他域名或调整配置时找不到对应文件。
五、配置验证与常见问题排查
保存成功后,在微信客户端内打开该域名下的网页,结合 JS-SDK 的调试模式(在 wx.config 参数中临时设置 debug: true)即可查看鉴权结果。如果返回 config:ok,表明安全域名与后端签名均已正常生效。
实际操作中最常遇到两类故障,分别对应“保存阶段”和“页面调用阶段”,按以下顺序逐项排查即可定位。
1. 后台提示“无法访问校验文件”或“校验失败”
- HTTP 强制跳转或鉴权拦截:部分站点将所有 HTTP 请求重定向到特定登录页,或设置了仅允许内网/特定 User-Agent 访问的防火墙规则(WAF)。微信服务端抓取校验文件时没有登录态,一旦被拦截或重定向到其他域名就会校验失败。需为
/MP_verify_*.txt单独配置匿名放行。 - HTTPS 证书链不完整或过期:如果站点默认仅开启 HTTPS 而 SSL 证书不受信任(如自签名证书、缺少中间证书),微信服务端握手时会直接中断。自测时可加上
curl -v确认 TLS 握手是否顺利完成。 - 域名解析或服务器线路限制:本地修改了电脑
hosts指向测试服务器,但公网 DNS 尚未生效或仍指向旧服务器,会导致本机浏览器打开正常、微信服务端却访问失败。此时应核对公网 DNS 解析结果,确保微信服务器能够连上真正存放了校验文件的公网机器。
2. 页面调用时报错 invalid url domain
该报错说明当前页面所在的域名与公众号后台配置的 JS 接口安全域名不匹配,常见原因包括:
- 当前访问域名与配置不一致:例如后台只填了
www.example.com,但用户在微信里打开的是m.example.com,或仍处于本地 IP / 临时测试域名下。需要补齐实际访问域名,或切换到已配置的域名访问。 wx.config传入的appId对应错了账号:多公众号或测试号并行开发时,前端如果使用了另一个公众号的appId生成签名,微信会去那个公众号的后台校验域名,从而报域名不合法。- 附带核对
invalid signature的关联混淆:如果确认域名无误却仍报错invalid signature,通常是因为后端计算 JS-SDK 签名所用的url与当前网页实际 URL 不一致(例如前端传入了带#哈希路由的地址,或者未对 URL 去除#及其后面部分)。前端向后端请求签名时,应动态获取window.location.href.split('#')[0]并进行 URL 编码传递,同时确保在配置完成后先关闭测试页面的缓存再重新打开验证。
JS 开发 App 性能优化指南:解决列表卡顿与内存泄漏问题
2026-11-17 19:46:25
JS前端数据加密真的安全吗?揭秘中间人攻击风险
2026-11-17 14:08:51
JS用innerHTML拼接还是createElement创建盒子更好
2026-11-17 09:01:05
前端 JS 导出大量数据到 Excel 卡顿怎么办?性能优化策略
2026-11-16 13:19:21
Gemini Robotics 2.5能力边界解析:动作模型、奔驰试点与物理安全验证
2026-11-16 11:23:07







