> For the complete documentation index, see [llms.txt](https://lizh.gitbook.io/knowledge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lizh.gitbook.io/knowledge/bugs/10-wei-xin-huan-jing-qian-duan-kai-fa-zhi-nan.md).

# 微信环境前端开发指南

## 微信环境的浏览器

### **微信公众号网页**

这是最接近标准浏览器的环境。

* **Android平台**：核心引擎是 **腾讯X5内核**（基于Blink深度定制），JavaScript 引擎是 **V8引擎**。
* **iOS平台：** 核心引擎是 **WKWebView**（苹果官方），JavaScript 引擎是 **JavaScriptCore**（Nitro引擎）。

微信公众号网页使用微信内置浏览器，可以访问完整的 Web API、支持常规 cookie、localStorage 等存储机制。

### **微信小程序原生**

这才是微信小程序的主要运行环境，**不是浏览器引擎**！

* **渲染层**：基于 **WebView（X5/WKWebView）** 但**只负责UI渲染**。
* **逻辑层**：独立的 **JavaScript运行时**，每个页面一个独立的 WebView 作为JS运行环境，通过 `JSCore` 或`V8`执行业务逻辑。
* **双线程通信**：通过 Native 层进行消息转发和序列化。

**关键限制：** 不支持 DOM/BOM API；CSS选择器有限（仅支持.class、#id等基础选择器），样式需要编译时处理。

微信小程序使用微信自研的渲染引擎，是混合渲染框架，底层用 WebView 做渲染，运行在微信小程序的沙盒环境中，只能使用微信提供的 API，不能直接访问 Web API，有自己的存储机制（wx.setStorage/wx.getStorage）。

### **微信小程序 WebView**

这是小程序内嵌的完整浏览器环境。

* **Android平台：使用与公众号相同的 X5内核，但与小程序主框架隔离运行**，具有独立的`JSCore`实例。
* **iOS平台：** 独立的 **WKWebView实例**，与小程序的 JS 环境完全隔离。

微信小程序 web-view 使用微信内置浏览器，运行在小程序**独立的沙箱**环境，可以访问完整的 Web API、支持 cookie、localStorage 等存储机制。

### 微信环境 Cookie 机制

* **微信公众号网页**：运行在微信内置浏览器（或系统浏览器）中，属于标准的浏览器环境，遵循常规的 Cookie 策略。
* **微信小程序原生**：有自己的存储机制（wx.setStorage/wx.getStorage）。
* **小程序 `web-view`**：运行在小程序提供的**独立的沙箱**环境中，虽然能加载网页，但其网络请求和存储机制与普通浏览器有所不同。

也就是说，**微信公众号网页、微信小程序、微信小程序 WebView 不共享 Cookie**。

若需共享状态，优先使用 **URL 参数传递 Token** 或 **服务器端设置 Cookie**。

## 微信公众号授权

* 测试环境授权，提示用户先关注公众号：这是测试公众号的限制，线上没有此问题。
* 当开发者在网页中在**不规范**使用发起 snsapi\_userinfo 网页授权时，微信将默认打开网页**快照页模式**进行基础浏览。[微信网页授权能力调整公告](https://developers.weixin.qq.com/community/minihome/doc/000c2c34068880629ced91a2f56001)

  常见的微信网页授权不规范使用案例：

  * \*\*强制登录：\*\*在用户打开网页时立即要求用户授权，用户拒绝后无法使用网页提供的服务；
  * \*\*违规收集个人信息：\*\*未在网页提前告知使用个人信息的目的、方式和范围；
  * \*\*非必要收集：\*\*非必要获取用户信息的网页，如文章、视频等，要求用户在浏览内容前登录；
  * \*\*差别对待微信用户：\*\*同样的网页在浏览器内可以无需登录直接访问，在微信内却要求用户先登录才可访问。

## 微信公众号域名配置

* **业务域名**：设置后，在微信内访问该域名下页面时，不会被重新排版。用户在该域名上进行输入时，不出现安全提示，比如提示：防诈骗盗号，请勿xxx。
* **JS接口安全域名**：设置后，公众号开发者可在该域名下调用微信开放的 JS 接口。**域名配置包含其子域名。**
* **网页授权域名**：用户在网页授权页同意授权给公众号后，微信会将授权数据传给一个回调页面，回调页面需在此域名下，以确保安全可靠。

## 微信环境跳转

公众号跳转小程序：

* 公众号自定义菜单跳转到小程序（**公众号需要关联小程序**）
* 开放标签跳转小程序；
* 发送模板消息跳转小程序。

公众号跳转视频号：

* 公众号目前没有开放标签能直接打开视频号视频的。
* 如果对方有链接可以链接到视频号，那就可以使用链接来跳转（比如：公众号发布一篇带视频号二维码的文章，用户扫描二维码链接视频号）。
* 跳转小程序，在小程序打开视频号视频。

## 相关问题

### 微信分享失败的原因

* 链接协议问题，避免使用 http 协议 或直接 `//`。
* 微信聊天窗口直接发送的链接（即显示为链接，而非卡片形式），无法配置分享信息。[详情](https://developers.weixin.qq.com/community/develop/doc/0006a8ada0cf7008afcd2c38951000)
* 签名接口调用失败，可能是公众号 id 不对，或者公众号未在【JS 接口安全域名】中配置当前页面的域名。

**注意**：小程序分享不传图片，默认使用页面快照。

### 微信小程序 webview，cookie 设置无效问题

设置 cookie 时，如果不设置 `secure` 和 `sameSite` 属性：

```javascript
document.cookie = "key=value; domain=.example.cn"
```

这种情况下，子域名是可以向父域名写入 cookie 的。

但是，如果设置了 `secure` 和 `sameSite: 'None'`：

```javascript
document.cookie = "key=value; domain=.example.cn; secure; sameSite=None"
```

这种情况下，子域名就无法向父域名写入 cookie 了。

这个现象的原因可能是：

* `secure` 和 `sameSite: 'None'` 是更严格的安全设置；
* 这些设置会触发浏览器更严格的安全检查；
* 微信小程序 webview 在处理这些安全 cookie 时可能有额外的限制。

\*\*解决方案：\*\*如果不需要 HTTPS 和跨站 cookie，可以去掉这些安全属性；如果需要这些安全属性，可以考虑使用服务器端设置 cookie。