微信开发常见问题概览

测试公众号授权为何要求先关注？

仅测试号存在该限制，已认证正式服务号无强制关注要求。

测试环境访问授权页面会提示先关注公众号才能获取用户信息；切勿将该交互逻辑直接上线。

注意：页面一进入就强制拉起 snsapi_userinfo 授权，微信会触发网页快照模式，用户仅能基础浏览，无法获取用户信息。

网页被微信渲染为快照页

不规范调用 snsapi_userinfo 授权时，微信自动降级为快照浏览模式。

高频触发场景：

• 进入页面立即强制授权，拒绝授权后无法使用页面；
• 未清晰告知收集信息用途、范围，索取用户隐私；
• 浏览资讯、视频等内容前置登录；
• 同一页面在系统浏览器可免登，微信内却强制登录。

规范方案：优先开放基础内容浏览，获取身份信息放在业务必要节点；页面明示授权目的；微信内置浏览器与外部浏览器保持一致访问策略。

JS-SDK分享失败，分享卡片无标题、封面图

按优先级排查三点：

• 协议规范：页面地址、分享link、封面图片均使用完整 https://，禁止 http:// 或协议相对地址 //；微信环境无法保证默认协议为HTTPS。
• 链接形式限制：聊天窗口直接粘贴纯文本链接，不属于JS-SDK可控卡片，无法自定义分享标题、封面。
• 签名异常：公众号AppID配置错误；页面域名不在JS接口安全域名列表；签名计算 URL 必须截取 location.href.split('#')[0]，前后端字符串完全一致；SPA路由切换后必须重新执行 wx.config。

分享接口使用新版：updateAppMessageShareData、updateTimelineShareData（旧版 onMenuShareAppMessage 已废弃）。

备注：小程序分享若未传入图片，默认截取页面快照作为封面。

开放标签 <wx-open-launch-weapp> 不显示、点击无响应

前置硬性条件：

• JS-SDK 版本 ≥1.6.0，页面同时引入低版本 jweixin 脚本时，会产生冲突；
• 账号资质：已认证服务号，或已认证非个人主体小程序云开发静态托管域名；
• wx.config 配置中必须声明 openTagList: ['wx-open-launch-weapp']；
• 按钮写在 <script type="text/wxtag-template"> 里（Vue 项目不要用 <template>，会被组件模板吃掉）；须由用户点击，不能脚本触发。

web-view 内 JS 无法写入父域 Cookie

小程序 web-view 属于独立 WebView 沙箱：Cookie、LocalStorage 与公众号 H5、小程序原生 wx.setStorage、系统浏览器完全隔离。

前端脚本执行如下代码极易失效：

document.cookie = 'key=value; domain=.example.cn; secure; sameSite=None'

Secure + SameSite=None 会启用严格跨站策略，微信 WebView 对 JS 动态写入父域 Cookie 限制更强。

解决方案：

• 无跨域需求：移除 Secure、SameSite=None；
• 需要写入父域 Cookie：由后端接口响应 Set-Cookie（完整证书链、HTTPS），避免前端JS操作父域Cookie。

额外约束：页面内嵌套 iframe 域名，同样需要配置小程序业务域名，否则页面加载失败。

web-view 页面白屏、JSSDK 调用无响应

逐项核对约束条件：

• 个人主体小程序禁止使用 web-view（海外主体小程序同样没有这项能力）；
• web-view src 域名必须配置小程序业务域名，或使用已关联公众号文章；
• URL 包含未编码中文：iOS 大概率出现白屏，所有参数统一使用 encodeURIComponent 编码；
• iOS 环境 JSSDK 失效：在链接末尾拼接 #wechat_redirect；
• 页面仅允许放置一个 web-view 组件，自动铺满全屏，层级最高，遮挡所有原生组件。

备注：开发者工具调试，右键 web-view 组件，打开独立调试面板。

注意：wx.miniProgram.postMessage 非实时推送，仅在页面后退、组件销毁、分享、复制链接时机触发小程序 bindmessage 回调。

编译报错：app.json 未找到

开发者工具根据 project.config.json 的 miniprogramRoot 定位 app.json，路径不匹配直接报错。

常见原因：

• 产物未构建：Taro、uni-app、kbone 要先 npm run dev、build，app.json 在编译产物目录，不在源码根上；
• 缺少工程配置：将产物目录内 project.config.json 复制到工具打开的根目录；
• miniprogramRoot 指错：必须指向含 app.json 的目录。Taro 微信端常见是 dist/weapp，不是 dist/；uni-app、kbone 以各自产物目录为准。

备注：project.private.config.json 内同名配置优先级高于公共配置；工具内修改 AppID、编译模式会写入私有配置文件。

开发者工具打开项目显示空白页

核心诱因：miniprogramRoot 目录配置错误。

以Taro为例，不要指向 dist，需要修改为 dist/weapp；也可直接导入产物目录。

真机空白额外排查：

• 使用 navigateTo 打开 tabBar 页面（路由规则不允许）；
• app.json 的 pages 数组第一项首页路径配置错误；
• 页面存在 JS 运行时报错阻断渲染。

编译报错：找不到 sitemap.json

app.json 中 sitemapLocation 指向路径不存在。

在 miniprogramRoot 目录新建 sitemap.json：

{
  "desc": "https://developers.weixin.qq.com/miniprogram/dev/framework/sitemap.html",
  "rules": [{ "action": "allow", "page": "*" }]
}

备注：该文件用于小程序搜索索引，缺失会导致编译失败。

如何清理小程序缓存

• 开发者工具：顶部「清缓存」，可区分数据缓存、文件缓存、授权信息；
• 手机端：删除对应小程序；开发版、体验版、正式版缓存相互隔离，排查问题需要全部清除。

注意：wx.setStorage 清理接口无法清除 web-view 内部 Cookie，网页存储需要页面自身清理或使用 URL 参数规避缓存问题。

接口在开发者工具正常，真机请求失败

开发者工具勾选「不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书」只对工具和手机调试模式有效；真机关掉调试后仍走白名单。

• 后台配置对应的服务器域名（request、upload、download、socket）；
• 接口必须为 HTTPS、WSS，域名完成ICP备案；证书链完整，支持 TLS 1.2 及以上；
• 不支持 IP 地址、localhost、微信官方接口域名 api.weixin.qq.com；父域名配置不代表子域名自动生效。

注意：4xx、5xx HTTP 状态码依旧进入 success 回调，业务必须手动判断 statusCode；页面切后台超过 5 秒未完成的请求，会中断并返回 fail interrupted。