公众号 H5 + 微信扫码功能 后台配置教程

前置要求

1. 公众号：已认证服务号（订阅号无扫码 JS 接口权限）
2. H5 站点：域名完成ICP 备案、全站支持 HTTPS
3. 提前准备：公众号 AppID、AppSecret

一、配置业务域名（H5 正常访问必配）

作用：避免微信拦截 H5、提示域名未被信任

1. 登录，进入 设置与开发 → 公众号设置
2. 切换到 功能设置，找到「业务域名」→ 点击设置
3. 点击添加，填写纯根域名（例：h5.xxx.com，不带 http/https、路径）
4. 下载微信校验 .txt 文件，上传至 H5 站点根目录
5. 验证：https://域名/校验文件名.txt 可直接访问，完成后保存

说明：单个公众号最多添加 3 个业务域名，配置即时生效。

二、配置 JS 接口安全域名（扫码 API 核心必配）

作用：授权 H5 调用微信 JS-SDK（扫一扫、分享等接口）

1. 仍在 公众号设置 → 功能设置，找到「JS 接口安全域名」→ 设置
2. 填写H5 根域名（格式同业务域名）
3. 下载校验文件，上传至站点根目录并外网可访问
4. 点击确定保存

注意：子域名场景直接填写完整子域名，如 h5.xxx.com。

三、获取开发密钥（签名生成必配）

用于后端生成 JS-SDK 签名，扫码功能依赖此项

1. 进入 设置与开发 → 开发管理，切换到 开发设置
2. 复制 开发者 ID (AppID)
3. 查看 开发者密码 (AppSecret)：点击重置，管理员微信扫码验证，复制保存

安全提醒：AppSecret 禁止放在前端代码，仅后端使用。

四、配置 IP 白名单（后端调用接口必配）

作用：放行后端服务器请求微信接口（获取access_token、签名等）

1. 开发管理 → 开发设置，下滑找到「IP 白名单」→ 配置
2. 填写后端服务器公网 IP，多 IP 用英文逗号分隔
3. 管理员扫码确认，保存生效

五、配置网页授权域名（选配）

仅 H5 需要获取用户 OpenID、昵称、自动登录时配置，纯扫码可跳过

1. 公众号设置 → 功能设置，找到「网页授权域名」→ 设置
2. 填写 H5 根域名，上传校验文件并保存

限制：仅支持配置 1 个域名。

六、发布 H5 入口（用户访问渠道）

1. 自定义菜单跳转 H5

1. 左侧 内容与互动 → 自定义菜单
2. 新增菜单，选择跳转网页
3. 粘贴完整 HTTPS 格式 H5 链接，保存并发布菜单

2. 二维码 / 图文跳转

1. 后台 工具 → 二维码，填入 H5 链接生成公众号二维码
2. 公众号图文编辑器直接插入 H5 链接，用户点击即可访问

七、常见问题排查

1. 扫码接口调用失败

   检查：是否认证服务号、JS 接口安全域名配置、校验文件外网可访问

2. 页面被拦截 / 无法打开

   检查：业务域名、域名备案、是否使用 HTTPS 协议

3. 后端获取 access_token 失败

   检查：AppID/AppSecret、服务器 IP 是否加入 IP 白名单

4. 域名校验失败

   检查：校验文件放在站点根目录、链接为 HTTPS、未修改文件名