轻舟已过万重山——H5 无缝跃迁小程序全攻略
项目：快缩短网址（suo.run）



一、缘起
在流量碎片化的时代，一条短链若能直抵小程序深处，便如暗门般将用户瞬间送达目的地。快缩短网址（suo.run）为此凝练出两条极简航道：URL Scheme 与微信 JSSDK。前者如飞鸿传书，后者似内家心法，各擅胜场。

二、航道一：URL Scheme——鸿雁于飞
1. 场景
短信、邮件、浏览器等一切微信外疆域。
2. 三步成诗
① 取钥
登录微信公众平台 → 小程序管理 → 工具 → 生成 URL Scheme
填路径：pages/detail/index?id=123
设有效期：≤30 日
② 铸链
suo.run 自动将 Scheme 封装为短链，形如：
https://suo.run/abc123
③ 投寄
任意 HTML 均可直引：
立即体验小程序
3. 锦囊
• 仅支持点击触发，不可静默跳转
• 若用户未装微信，suo.run 智能降级至应用商店引导页



三、航道二：JSSDK——灵犀一指
1. 场景
页面已在微信内 WebView 中呼吸。
2. 五步御剑
① 引剑

② 祭印（后端签名）
appId、timestamp、nonceStr、signature 由服务端算好，前端：
wx.config({
debug: false,
appId: 'YOUR_APP_ID',
timestamp: TIMESTAMP,
nonceStr: NONCESTR,
signature: SIGNATURE,
jsApiList: ['checkJsApi', 'miniProgram.navigateTo']
});
③ 探境
wx.ready(() => {
// 确认已在小程序环境
});
④ 御剑
wx.miniProgram.navigateTo({
url: '/pages/detail/index?id=123'
});
⑤ 善后
若 wx.miniProgram.getEnv 返回 false，suo.run 自动回退至 URL Scheme 方案。
3. 锦囊
• H5 域名须列入小程序业务域名
• 跳转路径需在 app.json 的 pages 字段中预先落户

四、彼岸清单
1. 路径先行
app.json 示例：
{
"pages": [
"pages/index/index",
"pages/detail/index"
]
}
2. 参数渡舟
• 简单键值：?id=123
• 巨量数据：先存云端，以 key 换取
3. 体验微雕
• 跳转前温柔提示：“即将前往小程序…”
• 失败场景优雅兜底：未装微信则引至下载页；路径未配置则回首页

五、问答小筑
Q1：能否跳至未声明的幽径？
A：否。小程序只认 app.json 的官道。
Q2：用户未装微信？
A：suo.run 自动识别，先邀其下载，再续前缘。
Q3：参数过长？
A：suo.run 提供云端缓存接口：POST /store → 返回短 key，小程序端再取。

六、收鞘
• 微信内：首选 JSSDK，灵动如风。
• 微信外：倚重 URL Scheme，简洁如雷。
辅以 suo.run 的短链、降级、数据缓存三重加持，H5 与小程序之间再无天堑，只剩一键瞬移的丝滑体验。