# 小程序一键接入

欢迎使用微信网关，下面将详细介绍微信小程序快速接入微信网关，使用微信网关守护业务数据及接口安全、抵御外部恶意流量以及提升业务访问质量的的操作步骤。整个接入会在 1-3 分钟内完成，无需修改代码、无需重新发版，且不影响业务线上运行。

另外，平台也配套上线了视频课程，你可以前往文档底部的视频课程学习这一部分。

## 一、接入步骤

### 1. 微信扫码登录 [微信开发者平台](https://developers.weixin.qq.com/console/?csrfRand=1067714125)进入平台首页
选择「我的服务 - 微信网关」，点击「去接入」，或者选择「网络链路 - 微信网关」，或者前往「小程序详情 - 服务范围 - 微信网关」

### 2. 首次登录且当前微信号下无微信网关空间，则需要先创建微信网关空间
![](https://res.wx.qq.com/op_res/A5K08onsO1BTHi0OKej0wHlA5u9qNl8jfuHR-xoieMRw8dLZJWP2OczUuZNQEkh48YT8mIAoMXTFbEoxKBivaA)

如当前微信号下无小程序，需前往微信公众平台注册小程序，再返回微信网关首页接入；
如当前微信号下已有微信网关空间但无微信网关，平台将默认选择首个微信网关空间，并在该空间下创建微信网关。支持手动切换空间；
如当前微信号下已有微信网关空间且已有微信网关，平台将默认将小程序接入到该微信网关下；

### 3. 进入微信网关首页，选择接入小程序，勾选同意微信网关功能服务条款，点击「接入」即可接入成功
![](https://res.wx.qq.com/op_res/wbOVt3RUWbtv3FqhrR_wNU3GY_AIzMuEQnEzk-bcNqn0kbJNfuTiEfa3m2WrNxsNJtWnOfj0ww3EPqpbBCIoFw)

- 可在微信网关首页右上角下拉框切换不同小程序接入；
- 微信网关默认将小程序体验版接入微信网关微信私有链路，完全不影响线上流量，仅用作小程序体验版测试使用，请放心接入；
- 如选择的小程序无体验版，请重新选择有体验版的小程序接入，或给当前小程序推送个体验版再次尝试接入；
- 如选择的小程序未在[微信公众平台](https://mp.weixin.qq.com/)配置 request 合法域名，则需前往「微信公众平台-开发-开发管理-开发设置-服务器域名-request 合法域名」中配置；
- 如选择的小程序在「微信公众平台」配置的 request 合法域名个数超过 20 个，平台将默认取线上有请求的前 10 个域名；
- 如当前微信号非选择的小程序管理员，则需要小程序管理员扫码授权；

### 4. 接入成功后即进入「网关概览」页面
- 小程序一键接入成功后，小程序体验版的所有请求都将由微信网关的「微信私有链路」保护后转发至小程序服务端；

### 5. 小程序线上版本接入微信网关，点击「前往接入配置」进入「业务配置」页面，选择目标小程序点击「修改」，将接入版本选择「全部版本」，选择所有小程序 URL，提交即可快速线上接入。

![](https://res.wx.qq.com/op_res/fthUPxST1LROJ7U2seHT1NJ6WtkgItIkYAAhigxHUg7yJM0JQrhEGR25D6XJ4r8kMaw0Pr4b-_xg7h0eLMvj1A)

接入版本列表及具体说明如下：

- 全部版本：包含小程序线上版、体验版、开发版 3 个版本；
- 体验版：仅小程序体验版请求接入微信网关；
- 开发版：仅小程序开发版请求接入微信网关；

另外，每个业务配置都有独立的接入开关，关闭接入开关后小程序所有版本请求都不接入微信网关，直接走原本的公网链路，不享受微信网关的安全防护及服务质量优化等能力。

![](https://res.wx.qq.com/op_res/fthUPxST1LROJ7U2seHT1AenLEUyx3yM8eDTIs9l6jlplo2ti3Gakc1gtkZOJ-ypqbpGdyduIi2ijoOYWBBs7A)

### 5. 小程序线上流量灰度接入微信网关，支持接口维度灰度接入。

- 小程序 URL，微信网关已打通[微信公众平台](https://mp.weixin.qq.com/)，自动拉取小程序对应的 request 合法域名；
- 你可按照业务情况，支持部分「小程序 URL」接入微信网关；
- 支持同个域名下添加多个路径，路径为空时默认按照前缀匹配；
- 如需添加新的小程序域名，请先前往「微信公众平台- request 合法域名」添加，再返回对应「接入域名」中操作；
- 小程序 URL 个数支持配置 20 个（更高规格的版本，该限制会有提升，具体看计费文档的细项说明）

![](https://res.wx.qq.com/op_res/fthUPxST1LROJ7U2seHT1J3UqEDXA-z_yicuC17skn9TO2BpMCZ6BjNxy2f2C_IvONMahzvOUtzAc4U2EBSB7A)

配置灰度接入时，需要注意以下几点：

1. 不可配置相同路径的不同灰度比例，或者不同的用户组
2. 不可配置嵌套形式的路径，比如同时配置 `/a/b` 和 `/a`

## 二、常见问题

### 1. 使用小程序一键接入微信网关后，是否还需要小程序发版？

答：不需要小程序发版，不需要修改小程序代码，小程序流量将按照你的配置接入微信网关，受微信网关微信私有链路保护和优化；

### 2. 如果接入的小程序流量大于微信网关套餐规格，超出的流量怎么处理？

答：超出的流量将走原业务公网链路，不再受微信网关微信私有链路保护和优化，建议升级微信网关套餐；微信网关不会阻塞/拦截丢弃正常的小程序流量。

### 3. 如果不想再使用微信网关，怎么操作？

答：微信网关支持小程序快速断开接入，快速断开后小程序流量将直接走原业务公网链路，流量不受阻塞；操作路径「业务配置-目标小程序-快速断开」，或者「业务配置-目标小程序-修改-关闭接入开关-提交」；

### 4. 如何判断请求是否经过了网关链路？

答：网关链路的 errmsg 值为 gateway.call:ok， 另外在返回体根级会有 callid，建议在小程序端记录并上报该 callid，链路出现问题可以凭此 callid 反馈给微信网关团队精确定位。服务端会收到安全链路的特定 header：

- x-wx-call-id：链路请求 ID，和前端响应的一致，可以通过其来联系前后端日志。反馈问题也首选这个。
- x-wx-route-tag：接入域名标记，可以根据此判断不同的接入域名转发的流量，用来区别对待
- x-wx-source：请求客户端，比如微信客户端是 wx_client，开发者工具是 wx_devtools
- x-wx-appid：请求小程序，标记请求的小程序 appid
- x-envoy-expected-rq-timeout-ms：网关参数，响应超时时间，一般是 15 秒

为安全考虑，关于网关的其他 header 信息，请在接入后发现，如有疑问请联系微信网关团队 1v1 解答。（不同的小程序接入时可能会有专门的 header 内容）

根据自身安全要求，可以通过 x-wx-appid、x-wx-route-tag 来设立一个白名单，只接受来自白名单接入域名或白名单小程序的请求。

### 5. 为什么接入配置后，小程序对应的版本访问还是原生链路，没有走安全链路？

答：可能以下 2 点原因：
a. 链路生效一般在 1 分钟之内，如果用户正在访问该小程序，则需要等待下一次启动打开才可以。如果开发者测试验证，则建议退出微信后台，重新进入再试，如果仍然不可以，则删除掉小程序然后重新加载尝试（删除掉小程序主要是清除缓存）

b. 小程序一键接入方式，暂未覆盖 PC 端小程序/低于 3.0.2 基础库版本小程序，验证请在手机端进行。

### 6. 为什么接入配置后，微信开发者工具没有走安全链路？

答：开发者工具对应的是「开发版」，需要保证接入配置到「开发版」上，配置之后仍然不可以则等待一分钟再试。一般清除缓存+重启开发者工具都可以搞定。基础库版本需要在 3.1.5 及以上，开发者工具版本需要在 1.06.2310312 及以上。

### 7. 为什么接入小程序后，经过微信网关的请求耗时明显增加了？（小程序端请求变慢了）

答：可能是以下 2 点原因：

a. 网关接入地域与小程序服务端部署地域存在跨域情况，导致因请求跨域而耗时增加；目前微信网关已上线选择「接入地域」能力，当前支持选择「上海」、「深圳」、「天津」3 个地域，后续会支持更多；为避免远距离跨域而导致请求耗时延长，请就近选择接入网关地域。例如，小程序服务端部署在深圳，请选择深圳地域；小程序服务端部署在北京，请就近选择天津地域。

b. 业务请求带宽超出免费试用版本的带宽额度，目前免费试用版带宽额度为 1Mbps；你可前往「微信网关控制台-监控视图-套餐监控」中查看「超出套餐带宽请求量」视图情况，并调整下业务请求回包大小，以避免带宽超额；

### 8. 一键接入支持到什么版本？
基础库版本：3.0.2 及以上

手机系统：Android，iOS，鸿蒙

如有其他问题，可前往[微信开发者社区-微信网关专区](https://developers.weixin.qq.com/community/minihome/mixflow/4105349690533838854)进行反馈提问.