微信小程序获取 URL Scheme

---

一、背景介绍

URL Scheme 是微信小程序提供的一种外部跳转能力，可用于短信、邮件、外部网页、微信内等场景拉起小程序指定页面。自 2023 年 12 月 19 日起，微信对 URL Scheme 进行了重大优化：

• 支持在加密 URL Scheme 后拼接自定义参数；
• 新增明文 URL Scheme，无需调用接口即可自行拼接生成；
• 取消“一人一链”限制，同一条链接可被多名用户访问；
• 每天 URL Scheme 和 URL Link 总打开次数上限为 300 万。

本文将详细介绍如何获取加密 URL Scheme 和明文 URL Scheme，以及相关注意事项。

---

二、准备工作

1. 开发工具准备

为了方便调试接口，推荐在 VS Code 中安装 REST Client 插件。该插件可以直接在编辑器中发送 HTTP 请求，无需借助 Postman 等外部工具，且能避免浏览器跨域问题。

2. 账号与权限要求

• URL Scheme 仅对非个人主体小程序开放；
• 需确保小程序已发布（仅能生成已发布小程序的 URL Scheme）；
• 准备好小程序的 AppID 和 AppSecret（可在微信公众平台获取）。

---

三、获取 Access Token

调用微信服务端接口需先获取 access_token，它是接口调用的凭证。

1. 接口说明

• 接口地址：GET https://api.weixin.qq.com/cgi-bin/token
• 请求参数：
  • grant_type：固定值 client_credential；
  • appid：小程序的 AppID；
  • secret：小程序的 AppSecret。
• 返回参数：
  • access_token：获取到的凭证，有效期 7200 秒（2 小时）；
  • expires_in：凭证有效时间，单位：秒。

2. REST Client 请求示例

创建 getAccessToken.http 文件，内容如下：

### 获取 access_token
GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=YOUR_APPID&secret=YOUR_APPSECRET HTTP/1.1

将 YOUR_APPID 和 YOUR_APPSECRET 替换为实际值，点击文件上方的“Send Request”即可发送请求。

3. 注意事项

• 安全存储：access_token 应在服务器端存储和刷新，切勿在前端代码中暴露；
• 缓存机制：由于 access_token 有效期为 2 小时，建议在服务器端缓存，避免频繁调用接口（每日调用次数有限制）；
• 错误处理：若返回 errcode: 41002，说明 appid 缺失，请检查请求参数。

---

四、获取 URL Scheme

URL Scheme 分为加密 URL Scheme 和明文 URL Scheme 两种，可根据需求选择。

方式一：获取加密 URL Scheme

需通过服务端接口生成，适用于需要严格控制链接有效期的场景。

1. 接口说明

• 接口地址：POST https://api.weixin.qq.com/wxa/generatescheme?access_token=ACCESS_TOKEN
• 请求参数：
  • access_token：URL 参数，填入上一步获取的 access_token；
  • jump_wxa：跳转参数对象，包含：
    • path：小程序页面路径（必填，不可携带 query）；
    • query：页面参数（选填，最大 1024 字符，支持 !#$&'()*+,/:;=?@-._~% 等字符）；
    • env_version：小程序版本（选填，release 正式版/trial 体验版/develop 开发版，仅微信外打开时生效）；
  • is_expire：是否设置过期时间（选填，true/false）；
  • expire_type：过期类型（选填，0 按时间戳/1 按间隔天数）；
  • expire_time：过期时间戳（expire_type 为 0 时必填，最长 30 天）；
  • expire_interval：过期间隔天数（expire_type 为 1 时必填，最长 30 天）。
• 返回参数：
  • openlink：生成的加密 URL Scheme，格式为 weixin://dl/business/?t=*TICKET*。

2. REST Client 请求示例

创建 getScheme.http 文件，内容如下：

### 获取加密 URL Scheme
POST https://api.weixin.qq.com/wxa/generatescheme?access_token=YOUR_ACCESS_TOKEN
Content-Type: application/json;charset=utf-8

{
  "jump_wxa": {
    "path": "/pages/index/index",
    "query": "id=123&name=test",
    "env_version": "release"
  },
  "is_expire": true,
  "expire_type": 1,
  "expire_interval": 7
}

将 YOUR_ACCESS_TOKEN 替换为实际值，点击“Send Request”即可获取加密 Scheme。

3. 拼接自定义参数

2023 年 12 月 19 日后生成的加密 Scheme，支持直接在后面拼接 cq 参数（需 URL 编码）：

weixin://dl/business/?t=*TICKET*&cq=url_encode("custom_param=value")

---

方式二：生成明文 URL Scheme（推荐）

无需调用接口，在微信公众平台声明后即可自行拼接，更简单高效。

1. 前置声明

登录微信公众平台，进入「设置 - 基本设置 - 隐私与安全 - 明文 Scheme 拉起此小程序」，完成声明。

2. 拼接规则

明文 URL Scheme 格式如下：

weixin://dl/business/?appid=APPID&path=PATH&query=QUERY&env_version=ENV_VERSION

参数说明：

• appid：小程序 AppID（必填）；
• path：小程序页面路径（必填，不可携带 query）；
• query：页面参数（选填，最大 512 字符，需 URL 编码）；
• env_version：小程序版本（选填，默认 release）。

3. 示例

weixin://dl/business/?appid=wx1234567890abcdef&path=/pages/index/index&query=id%3D123%26name%3Dtest&env_version=release

---

五、URL Scheme 的使用

1. 场景说明

URL Scheme 适用于以下场景：

• 短信、邮件中点击链接拉起小程序；
• 外部网页（非微信内）跳转小程序；
• 微信内网页（需使用开放标签，见下文）。

2. 系统兼容性

• iOS：支持直接识别 URL Scheme，可在短信等应用中直接点击跳转；
• Android：不支持直接识别，需通过 H5 页面中转，跳转代码示例：

  location.href = 'weixin://dl/business/?t=*TICKET*';

3. 微信内网页跳转

微信内网页如需跳转小程序，不建议使用 URL Scheme，应使用微信开放标签 <wx-open-launch-weapp>，或通过云开发静态网站实现免鉴权跳转（详见参考文档）。

---

六、注意事项与常见问题

1. 频率限制

• 生成端：每天生成加密 URL Scheme 和 URL Link 总数量上限为 50 万；
• 打开端：每天通过 URL Scheme（加密+明文）和 URL Link 打开小程序总次数上限为 300 万。

2. 错误码排查

错误码	说明	解决方案
40001	access_token 无效	检查 access_token 是否过期或正确
40165	页面路径无效	确认 path 是已发布小程序的存在页面
40212	参数格式错误	检查 query 是否符合 URL 规范
85079	小程序未发布	仅能生成已发布小程序的 URL Scheme

3. 其他注意事项

• 只能生成已发布小程序的 URL Scheme；
• 通过 URL Scheme 跳转时，可能触发系统弹框询问用户是否跳转，需妥善处理用户拒绝的场景；
• 部分浏览器限制直接跳转 Scheme，建议在 H5 页面设置跳转按钮引导用户点击。

---

七、最佳实践

1. 优先使用明文 Scheme：无需调用接口，拼接简单，适合大多数场景；
2. 合理设置有效期：加密 Scheme 按需设置过期时间，避免长期有效链接被滥用；
3. 参数编码：query 和自定义参数需进行 URL 编码，避免特殊字符导致解析失败；
4. 服务器端生成：加密 Scheme 的获取应在服务器端完成，避免暴露 access_token；
5. 多场景测试：在 iOS、Android 不同系统和浏览器中测试跳转效果，确保兼容性。

---

参考文档

1. 获取 access_token 官方文档
2. 获取加密 URL Scheme 接口文档
3. URL Scheme 框架文档
4. 云开发静态网站跳转小程序