weixin_share_tag
User 69e88e27
发布于：2025-08-29
## 微信分享：`weixin_share_tag`
## 1. 概述
`weixin_share_tag` 是布局专用的 Liquid 标签，用于在站点页面中接入微信相关能力：
- **微信内置浏览器**：注入微信 JS-SDK 配置，并设置「发送给朋友」「分享到朋友圈」的标题、描述、链接与图片。
- **微信小程序 `web-view` 内嵌站点 H5**：自动通过 **postMessage** 向小程序推送当前页的分享元数据，便于小程序在「转发给好友」等场景下与站点内容保持一致。
分享文案与配图**不由标签手写**，而是由系统根据当前页面与站点的 SEO / Meta 信息自动汇总（见第 6 节）。
---
## 2. 模板中的用法
### 2.1 使用位置
- 仅在 **布局文件**（如 `layouts/theme.liquid`）中使用，一般放在 `<head>` 中。
### 2.2 引入脚本
标签依赖主题共享脚本中的微信能力（含 `window.baklibWhenWxReady` 等）。在布局中引入其一即可：
```liquid
{{ 'baklib/shared/main.js' | asset_url | script_tag: data-turbo-track: 'reload' }}
```
或仅引入微信模块：
```liquid
{{ 'baklib/shared/weixin.js' | asset_url | script_tag: data-turbo-track: 'reload' }}
```
### 2.3 配置标签
- 标签配置（请直接复制进模板布局文件head标签中，一般无需修改调整）
```liquid
{% weixin_share_tag
app_id: site.settings.weixin_app_id,
app_secret: site.settings.weixin_app_secret,
access_token_url: site.settings.weixin_access_token_url,
debug: site.settings.weixin_debug,
enabled: site.settings.weixin_enabled
%}
```
- 参数说明：
| 属性 | 说明 |
|------|------|
| `app_id` | 微信公众平台 AppID；启用分享且需服务端签名时必填。 |
| `app_secret` | 微信公众平台 AppSecret；同上。 |
| `access_token_url` | 可选。自定义 access_token 获取地址；不填则使用默认逻辑。 |
| `debug` | 可选。为真时，签名失败或 JSSDK 错误等情况下可通过弹窗 / 控制台辅助排查（仅建议在配置阶段开启）。 |
| `enabled` | 可选。为假时标签不输出任何内容。 |
---
## 3. 主题后台配置（`settings_schema.json`）
建议在 `config/settings_schema.json` 中增加设置项，供站点在后台填写微信参数，模板通过 `site.settings.*` 引用。使用与配置（一般无需修改，直接写入config/settings_schema.json中）：
```json
{
"name": "t:schema.settings.weixin_share.title",
"settings": [
{
"id": "weixin_app_id",
"type": "text",
"label": "开发者ID(AppID)",
"info": "<a href='https://mp.weixin.qq.com/cgi-bin/frame'>微信公众号/设置与开发/开发接口管理</a>中获取"
},
{
"id": "weixin_app_secret",
"type": "text",
"label": "开发者密码(AppSecret)",
"info": ""
},
{
"id": "weixin_access_token_url",
"type": "text",
"label": "Access Token URL（可选）",
"info": "一般留空；仅在使用自定义 token 端点时填写"
},
{
"id": "weixin_enabled",
"type": "checkbox",
"label": "是否启用微信分享",
"default": false,
"info": "提供站点页面微信分享的能力</br>1. 请在微信公众号中配置 IP 白名单（ip: ${service_ip}），配置后将有一段时间的生效延迟。</br>2. 检查是否开启微信分享权限，微信公众号/设置与开发/开发接口管理: <a href='https://mp.weixin.qq.com/cgi-bin/frame'>网页服务/分享接口</a>。</br>3. 分享链接是否为卡片：从卡片形式进入分享卡片形式，链接形式进入分享链接形式；网页初始链接分享可由公司的服务号中或收藏后进行卡片分享（此规则为微信分享限制）。"
},
{
"id": "weixin_debug",
"type": "checkbox",
"label": "是否开启 debug 提示",
"default": false,
"info": "请仅在配置阶段开启此选项；开启后在访问前端站点时若未正确配置微信分享将自动提示错误信息"
}
]
}
```
---
## 4. 微信公众平台配置说明
### 4.1 AppID 与 AppSecret
登录 [微信公众平台](https://mp.weixin.qq.com/)，进入 **开发 > 基本配置**，可查看 AppID、AppSecret。
**说明：** 使用网页分享等相关接口通常需要 **已认证的服务号**（以微信官方文档为准）。
### 4.2 IP 白名单
- ip配置至 微信公众平台 → 开发 > 基本配置 ip白名单中
- 具体 IP地址可在站点配置中微信分享配置中获取
- 白名单配置保存后，通常需要等待 几小时左右 才会生效
### 4.3 分享接口权限
在 **设置与开发 > 接口权限** 中确认已开通 **网页服务 / 分享接口** 等所需能力。
---
## 5. 分享效果与展示形态
### 5.1 卡片与链接形态
- **卡片分享**：用户从公众号菜单、收藏等入口进入页面后再分享，通常展示带标题、描述、缩略图的卡片。
- **链接分享**：用户直接打开或复制链接进入时，分享形态可能仅为链接，属微信客户端规则，与标签配置无关。
---
## 6. 分享内容来源（Meta）
以下内容由系统自动从页面与站点 Meta 等信息推导，用于 H5 JSSDK 与小程序 postMessage **共用同一套数据**：
| 项目 | 说明 |
|------|------|
| 标题 | 页面 title 与站点名称等组合（与实现一致） |
| 描述 | 页面 description，可回退到站点首页等 |
| 链接 | 当前页面 URL |
| 图片 | 页面 icon / `image_src` 等，可回退站点 favicon 或系统默认 logo |
请通过页面 SEO、站点 favicon 等保证上述信息准确。
---
## 7. 小程序集成站点后的分享数据对接
当小程序通过 **`web-view` 加载站点 H5**，且站点布局中已启用 `weixin_share_tag`（`enabled` 为真、微信公众平台参数配置正确）时，页面脚本会在 **小程序环境** 下调用 `wx.miniProgram.postMessage`，把当前页的分享元数据发给小程序。若希望在「转发给好友」等场景下与 H5 当前页标题、封面、链接一致，小程序需要监听 `web-view` 消息、缓存最近一次有效数据，并在 `onShareAppMessage`（以及你方其它分享入口）里组装返回值。
### 7.1 `postMessage` 的数据结构
- data 数据
H5 侧调用形式为：`wx.miniProgram.postMessage({ data: <对象> })`。本标签传入的 **`data` 为单个对象**（不是数组），结构如下。
| 字段 | 类型 | 说明 |
|------|------|------|
| `__baklib_mp_bridge__` | 布尔 | 固定为 `true`，用于与其它 `postMessage` 区分。 |
| `event` | 字符串 | 固定为 `"weixin.share_meta"`，表示分享元数据。 |
| `timestamp` | 数字 | 发送时的毫秒时间戳。 |
| `payload` | 对象 | 分享业务字段。 |
- payload 数据
| 字段 | 含义 |
|------|------|
| `title` | 分享标题 |
| `desc` | 摘要描述 |
| `link` | 当前 H5 页完整 URL，用于回访站点对应页面 |
| `imgUrl` | 分享配图 URL |
- 示例：
```json
{
"__baklib_mp_bridge__": true,
"version": "1.0",
"event": "weixin.share_meta",
"timestamp": 1710000000000,
"payload": {
"title": "文章标题 - 站点名称",
"desc": "页面摘要",
"link": "https://example.com/path/to/page",
"imgUrl": "https://example.com/share.png"
}
}
```
微信文档中，`web-view` 的 **`message` 事件里 `detail.data` 为数组**：其中每个元素对应一次（或一批）`postMessage` 的 `data`。解析时需遍历 `data`，找到 `event === "weixin.share_meta"` 且 `payload` 为对象的项再使用。
### 7.2 小程序侧接入方式
1. 在承载站点的 **`web-view` 上绑定消息回调**（例如微信小程序的 `bindmessage`，或使用你所用框架提供的等价 API）。
2. 在回调中读取 **`detail.data`**（数组），遍历每一项；可优先判断 `__baklib_mp_bridge__ === true`、`version === "1.0"`、`event === "weixin.share_meta"`，再读取 `payload`。
3. 将 `payload` 中的 `title`、`desc`、`link`、`imgUrl` **写入本页或全局可访问的状态**（如页面 data、store 等），供分享时使用。若你方分享 API 使用 `url`、`imageUrl` 等字段名，可在这一步做字段映射。
4. 在 **`onShareAppMessage`** 中读取上述缓存，设置小程序分享的 `title`、`imageUrl`，并通过 **`path` / `query` 等把你方打开 `web-view` 所需的参数带上**（常见做法是把 `link` 编码进 query，打开 `web-view` 时再解码为站点 URL），保证好友点开分享卡片后仍能进入当前 H5 页面对应地址。
具体 API 名称以微信官方文档及你所用小程序框架为准；上述步骤描述的是通用接入顺序。
### 7.3 注意事项
- **送达时机**：`postMessage` 的数据往往在用户进行**分享、复制链接、返回**等操作时才会被送到小程序逻辑层，而不是页面每次渲染立即送达。不要假设首屏加载完成时一定已收到最新消息；分享时应尽量使用**最近一次成功解析**的 `payload`，并接受短窗口内信息与当前页不完全同步的可能。
- **多次发送**：用户在站点内跳转时，每一页若都带有本标签，可能多次 `postMessage`。小程序侧宜**每次收到 `weixin.share_meta` 就更新缓存**，以当前页为准。
- **字段名**：业务层若只识别 `url`、`imageUrl`，须自行与 `link`、`imgUrl` 对齐，避免封面或回访链接为空。
- **站点与小程序配置**：`web-view` 加载的站点域名需在小程序后台配置为**业务域名**；站点本身须 **HTTPS**，且微信侧能力（如合法校验）需满足官方要求，否则 H5 无法正常执行到 `postMessage`。
---
## 8. 常见问题（FAQ）
**为什么看不到分享按钮？**
分享入口由微信客户端提供；标签只负责配置分享内容或向小程序上报元数据。
**分享信息不正确？**
检查页面 Meta（title、description、image 相关）及站点 favicon 等。
**报错「不在 IP 白名单内」？**
在公众平台核对服务器出口 IP 与白名单一致，并等待生效。
**为什么分享形态有时只有链接？**
见第 5.1 节，属微信展示规则。
**如何调试 H5 签名与 JSSDK？**
开启 `debug: true`，根据弹窗或控制台输出排查。