微信环境开发指南
微信前端开发首先要分清三种运行容器：公众号网页、小程序原生、小程序 web-view。三者的渲染内核、存储隔离规则、可用 API、域名白名单体系均存在巨大差异，不能直接按照通用浏览器的思维进行开发与适配。
官方参考文档：公众号 JS-SDK 开发文档、小程序官方开发文档
运行环境
公众号网页（微信内置浏览器）
最贴近标准浏览器环境，完整支持 DOM、BOM、Cookie、localStorage；想要调用微信分享、扫一扫等原生能力，需要引入并初始化 JS-SDK。
- iOS：底层为 WKWebView + JavaScriptCore
- Android：使用微信定制 XWeb（原 X5）内核
- 鸿蒙：UA 会同时携带
ArkWeb、MicroMessenger标识
小程序原生环境
不属于完整浏览器环境，采用逻辑层、渲染层双线程分离架构。全部网络、事件调用都经过微信客户端 Native 转发、序列化处理。
- 逻辑层：执行业务 JavaScript，不存在 window、document，无法操作 DOM，jQuery 等 Web DOM 类库无法直接运行。iOS 下关闭 JIT，JS 执行性能弱于 Android；Android 使用 V8，Windows/Mac 开发者工具基于 NW.js、Electron。
- 渲染层：依靠 WXML、WXSS 完成页面渲染，每一个页面对应独立 WebView 实例。
- 数据通信：采用数据驱动视图更新，用户事件由渲染层回传给逻辑层。
- 网络能力：没有标准
XMLHttpRequest，网络请求必须使用小程序专属网络 API。 - 本地存储：只可以使用
wx.setStorage、wx.getStorage；和浏览器的 Cookie、localStorage完全隔离，互不互通。
小程序 web-view
小程序内部嵌入的完整 H5 容器，和小程序原生逻辑层完全隔离。
- 内核跟随宿主系统：iOS 使用独立 WKWebView，Android 使用 XWeb 内核。
- 完整支持标准 Web API、Cookie、
localStorage，普通 H5 代码可以直接运行。 - 可以使用 JS-SDK 1.3.2 以上版本提供的有限接口，完成和小程序宿主之间的跳转交互。
环境存储隔离规则
公众号 H5、小程序原生、小程序 web-view，三者本地存储完全隔离，不会自动共享 Cookie、localStorage。
注意：不能依靠域名实现登录态互通；跨环境传递登录凭证，优先使用 URL 参数传参、服务端 Set-Cookie 下发实现。
运行环境判断代码
建议等待 WeixinJSBridgeReady 事件就绪之后再做环境判断，结果会更加准确。
function isMiniProgramWebView() {
return window.__wxjs_environment === 'miniprogram' || /miniProgram/i.test(navigator.userAgent)
}
备注：微信 7.0.0 及以上 UA 会携带 miniProgram 标识；8.0.16、8.0.17 版本之后 UA 额外附带小程序 AppID。
公众号网页开发
三类核心域名配置
在公众号后台「公众号设置 → 功能设置」页面配置域名。
规则：域名不能携带协议、端口号；域名必须完成 ICP 备案；新备案域名一般需要等待约 24 小时才正式生效。
绑定父域名，其合法子域名自动生效；网页授权域名为精确全域名匹配，配置 www.example.com 不等于包含 pay.example.com。
业务域名、JS 接口安全域名、网页授权域名三者互相独立，配置互不通用：
- 业务域名：规避页面被微信强制重排版，屏蔽风险诈骗弹窗提示。
- JS 接口安全域名：控制 JS-SDK 接口调用权限（分享、扫码等），最多填写 5 个，IP 地址、端口、短链不支持。
- 网页授权域名：用于 OAuth 回调
redirect_uri域名校验，严格全域名匹配；仅已认证服务号可用。
备注：页面能够正常打开 ≠ JS-SDK 可以正常调用；JS-SDK 调用正常 ≠ 网页 OAuth 授权可以正常使用。
JS-SDK 配置与签名规范
凡是需要调用微信原生接口的页面，必须执行 wx.config 做权限注入。SPA 使用 history 模式路由切换 URL 之后，必须重新做签名与 config 初始化。
签名核心规则：取当前页面 URL 中 # 哈希符号之前的完整地址，前端、后端参与签名的 URL 字符串必须完全一致。
wx.config({
appId: '',
timestamp: 0,
nonceStr: '',
signature: '',
jsApiList: ['updateAppMessageShareData', 'updateTimelineShareData'],
openTagList: ['wx-open-launch-weapp'] // 使用开放标签跳转小程序时必须配置
})
wx.ready(function () {
// 使用新版分享接口，旧版 onMenuShare 系列接口已经废弃
wx.updateAppMessageShareData({
title: '',
desc: '',
link: '',
imgUrl: ''
})
wx.updateTimelineShareData({
title: '',
link: '',
imgUrl: ''
})
})
分享业务规则
- 只有卡片链接形式才会生效自定义标题、封面图；直接粘贴普通文本链接不会触发卡片样式。
link域名必须属于 JS 接口安全域名；必须使用 HTTPS 完整地址，不允许使用 HTTP、协议相对路径。
网页授权 OAuth
仅已认证服务号支持网页 OAuth，通过 code 换取用户 access_token。
snsapi_base：静默授权，不会弹出授权弹窗，仅拿到用户 openid。snsapi_userinfo：弹窗申请用户授权，可以获取昵称、头像等完整用户资料。
违规风险：没有合理告知授权用途、强制登录、浏览内容前置登录，微信会强制降级为网页快照模式，无法获取用户信息。
注意：redirect_uri 必须为 HTTPS 域名；授权链接参数顺序严格遵循官方文档，顺序错误会造成跳转异常。
跨端跳转能力
公众号跳转小程序
- 自定义菜单跳转：公众号后台关联目标小程序后配置。
- 开放标签
<wx-open-launch-weapp>跳转（场景值 1167），依赖 JS-SDK 1.6.0 及以上版本，必须由用户手动点击触发。 - 模板消息、订阅通知配置跳转小程序路径。
<wx-open-launch-weapp appid="wxxxxx" path="pages/index/index" env-version="release">
<script type="text/wxtag-template"></script>
</wx-open-launch-weapp>
env-version 可选：release 正式版、trial 体验版、develop 开发版。Vue 项目不要使用 <template> 嵌套按钮元素，会被模板编译机制吞噬。
其它跳转限制
- 公众号网页没有直接打开视频号的开放标签，可借助二维码、小程序中转调用视频号相关能力。
- 跳转 App 使用开放标签
<wx-open-launch-app>。
小程序原生开发
运行环境与基础库
小程序支持 iOS、Android、鸿蒙、Windows、Mac 多端。
基础库内嵌于微信客户端，小程序的接口能力由用户手机上微信版本决定。项目后台可以设置最低基础库版本，微信版本过低的用户会提示升级微信。
备注：开发工具可以通过 ES6 转译、样式兼容抹平大部分差异；最终兼容性以真机微信客户端为准。
小程序生命周期
- 冷启动：首次打开、进程销毁后重新打开，完整初始化，执行
onLoad。 - 热启动：从后台切回前台，不会执行
onLoad；页面数据刷新逻辑写在onShow。 - 后台状态：退到后台短时间 JS 代码仍可以执行，但部分 API 被限制。
- 挂起状态：后台静置 5 秒后，JS 线程暂停，内存数据保留；后台播放音频、后台定位可免于挂起。
- 销毁状态：后台静置 30 分钟、内存紧张、iOS 内存告警会销毁小程序进程；可监听
wx.onMemoryWarning做资源释放清理。
语法与样式约束
- 禁止直接使用
eval、new Function动态生成函数（官方明确豁免场景除外）。 - 基础库内置
core-js补齐部分低端环境 API，ES6+ 语法仍然需要构建转译。 - iOS 15 及以下版本 Promise 由
setTimeout模拟，不是标准微任务，事件时序会存在差异。 - WXML 不支持
table标签；禁止动态远程加载 JS、CSS 脚本。 - WXSS 背景图片不支持本地相对资源，只支持网络图片、Base64、image 组件。
网络请求规范
wx.request、uploadFile、downloadFile、connectSocket 网络接口强制约束：
- 协议仅支持 HTTPS、WSS；域名需要完成 ICP 备案，并且配置小程序后台服务器域名白名单。
- 不允许填写 IP、
localhost；不支持父域名通配；微信官方接口域名不能配置进白名单。 - TLS 版本必须 TLS 1.2 及以上，iOS 拒绝自签名证书。
- 开发者工具可以关闭域名校验做调试，真机运行必须严格遵循白名单规则。
请求行为特性：
- 4xx、5xx HTTP 状态码都会进入
success回调，业务代码必须手动判断状态码处理错误。 - 普通请求最大并发 10 个，Socket 最大并发 5 个。
- 退到后台 5 秒还未完成的网络请求，会直接中断返回
interrupted错误。
小程序 web-view 详细规则
- 单个页面仅能放置一个
web-view，组件默认铺满全屏，层级最高，会覆盖全部原生组件。 - 个人主体小程序不允许使用 web-view 组件。
- 内嵌 H5 页面域名，需要配置小程序后台业务域名；或者打开已经关联公众号的文章；内部 iframe 域名同样需要遵守该白名单。
H5 与小程序宿主桥接 API（wx.miniProgram）
H5 页面只可以调用有限宿主能力：navigateTo、navigateBack、switchTab、reLaunch、redirectTo、postMessage、getEnv。
postMessage不是实时消息通道，消息不会立刻推送；仅在小程序后退、组件销毁、分享、复制链接时机才会触发小程序侧bindmessage事件。
iOS 兼容坑点（WKWebView 共性，公众号 H5 同样复现）
- web-view 的
src末尾拼接#wechat_redirect，可以修复部分 JS-SDK 调用无响应问题。 - URL 参数禁止直接携带未编码中文，极易造成页面白屏；所有参数统一使用
encodeURIComponent编码。
小程序路由 API
navigateTo：打开非 Tab 页面，保留页面栈，页面栈上限 10 层；不能跳转 Tab 页面。switchTab：专门跳转 Tab 页面，同时关闭其余非 Tab 页面。redirectTo：关闭当前页面，跳转新页面。reLaunch：清空全部页面栈，重新跳转目标页面。
主流跨端开发框架
小程序原生开发使用 WXML、WXSS、JS；想要一套代码多端运行，需要跨端框架。
- Taro：支持 React、Vue 两套语法，编译输出小程序、H5、React Native 等多端，企业项目主流选型。
- uni-app：基于 Vue 语法，全端覆盖，生态成熟，上手门槛低。
- kbone：Web 同构方案，模拟 DOM/BOM 环境，适合已有 Vue/React H5 项目迁移到小程序。
提示：mpvue 已经停止维护，新项目禁止选用。
工程配置文件说明
project.config.json：公共工程配置，建议提交到版本管理。project.private.config.json：优先级高于同名配置项，存放 AppID、调试参数；是否纳入版本库团队自行约定。
总结
- 开发前优先确认当前运行容器；公众号网页、小程序原生、web-view 三者内核、存储、API 互相隔离，不能复用同一套适配逻辑。
- 公众号 H5 重点把控三类域名配置、JS-SDK 签名、OAuth 网页授权、开放标签跳转规则。
- 小程序原生为双线程架构，没有 DOM 环境；开发需要遵守网络白名单、语法限制，重视页面生命周期，区分冷热启动。
- web-view 属于独立 H5 容器，要单独处理域名白名单、桥接通信、iOS WKWebView 兼容问题。
- 跨端项目优先选择 Taro、uni-app；放弃已经停止维护的老旧框架，统一项目工程配置规范。