企业官网建设流程全解析

三年前我第一次接钱包 SDK，卡在“唤起”这一步整整两天：Android 上一点就拉起，iOS 上点一百次都没反应，最后发现只是通用链接的域名校验文件没下发到位。这种问题在任何一份钱包集成文档里都不会写，但几乎每个团队都会撞上一次。后来我又踩过回调被别的 App 抢走、签名结果被服务端判为无效、用户切换账户后本地状态没失效导致下单失败等各种坑。把 TokenPocket 这类移动端钱包接进自己的产品，技术难度其实不高，难的是安全接入的边界意识和跨平台一致性这两件事。

这篇内容面向已经懂基本客户端开发、准备或正在做钱包集成的人，也包括正在评估“要不要接钱包”的产品和技术负责人。我会把三条集成路径的取舍、跨平台适配的工程结构、握手链路里的参数细节、安全红线以及排错方法拆开讲，尽量给到可以直接照着做的配置和检查项。钱包集成不是“调一个 SDK 就完事”的活，它是一条从客户端唤起、到钱包内签名、再到服务端验签的完整链路，任何一环松了，前面做得再漂亮也没意义。

1. 先把集成的边界画清楚：钱包能给你什么，不会给你什么

1.1 钱包端真正提供的三样能力

很多人对钱包集成的第一反应是“我要接一个支付”，这个认知偏差会直接导致架构设计跑偏。钱包不是一个支付渠道，它本质上是密钥的持有者和签名的执行者。你交给它一段待签内容，它在自己的安全环境里确认用户意图，然后把签名结果还给你。整个过程里，你的应用从头到尾都不应该接触到私钥、助记词或者 keystore 文件。

以 TokenPocket 这类主流移动端钱包为例，它在集成场景下提供的能力大致可以归为三类。第一类是账户发现，也就是在用户授权后返回一个或多个地址（address）以及当前所处的链（chainId）。注意这里返回的是地址，不是身份凭证，地址本身不具备任何认证效力，它只是一个公钥的哈希派生结果，谁都能看到。第二类是签名能力，包括对普通消息的签名（常见于登录场景的 challenge 签名）和对交易结构体的签名。第三类是交互 UI，也就是钱包自己弹出的确认页、授权页、风险提示页，这部分是钱包方负责的，你不要试图在自己的 App 里重新实现一遍，重实现等于绕过用户确认，是明确的安全事故。

反过来讲，钱包不会替你做的事情也很清楚。它不会托管资金，不会帮你做账务对账，不会替你判断这笔交易该不该做，更不会在你的服务端出问题时兜底。有些团队会问“钱包能不能帮我查余额”，能，但那是通过节点 RPC 查的，和签名能力是两条完全独立的链路。把这两条链路混在一起设计，后期一定会出问题：节点挂了不该影响签名，签名失败也不该让余额展示崩掉。

我一个很实用的判断标准是：凡是涉及“用户意图确认”的动作，都必须发生在钱包端；凡是涉及“业务规则判断”的动作，都必须发生在你的服务端。中间那条线就是签名结果，它是一条单向的、不可伪造的证据。沿着这条线去拆模块，架构基本不会错。

1.2 三条路径：内嵌 SDK、深度链接、中继会话

实际工程里能走的路只有三条，不存在第四种，认清这一点能省掉大量试错。

内嵌 SDK是把钱包的签名能力以库的形式打进你的 App，用户在你的 App 内直接唤起钱包的授权界面，签完原地返回。它的优势是链路最短、体验最顺、没有跨 App 跳转的损耗；劣势是包体会变大，而且 SDK 版本跟着钱包方走，你需要为升级维护成本做预算。这条路在移动端 DApp 浏览器类产品里最常见。

深度链接（Deep Link）是通过自定义 URI Scheme 或通用链接把用户从你的 App 送到钱包 App，用户签完之后再通过回跳参数把你拉回来。它的优势是零包体成本、钱包方升级你完全无感；劣势是链路长、环节多，唤起失败、回跳丢失、参数被截断这类问题会占掉你相当一部分调试时间。

中继式会话协议是双方各自连到一个中继服务，通过二维码或长连接交换消息。它的优势是跨端一致性极好，Web、桌面、移动端可以用同一套逻辑；劣势是多了一次网络往返，首次连接的等待感明显，而且对中继服务的可用性有依赖。

这张表里最容易被低估的是“跨端一致性”这一列。如果你的产品同时有 Web、iOS、Android 三个入口，选内嵌 SDK 意味着你要维护三套实现和三套问题排查经验；选中继会话则意味着你只需要维护一套协议逻辑，代价是首次连接的等待。我的建议是：移动端为主、Web 为辅的产品走深度链接加内嵌的混合方案；以 Web 和桌面为主的产品直接上中继会话，别犹豫。

1.3 选型时真正该问的三个问题

第一个问题：用户从你的产品里点“连接钱包”，平均要等多久？这个数字直接决定了你的转化。深度链接在冷启动场景下（钱包 App 没在后台）可能要 3 到 8 秒，中继会话首次扫码握手通常在 2 到 5 秒，内嵌基本在 1 秒内。如果你的核心流程对这一步极其敏感，那就得优先考虑内嵌。

第二个问题：你的用户主要在什么设备上操作？移动端浏览器的深度链接成功率远低于原生 App 内，因为各种内置浏览器对 Scheme 的拦截策略不一样。如果你的流量大头来自移动端 WebView，深度链接的失败率会高到让你怀疑人生，这时候中继会话反而是更稳的选择。

第三个问题：你能接受多长的升级周期？内嵌 SDK 一旦钱包方做了不兼容变更，你得发版；发版意味着审核、灰度、用户不升级的存量问题。深度链接和中继会话则是协议层解耦的，钱包方升级对你基本透明，前提是你自己做好了版本协商——这部分我在第 6 节会详细讲。

这三个问题问完，选型基本就定了。最怕的是先选了一个方案，做到一半发现不合适再换，那前面的会话管理、错误码、回调处理全部要重写。

2. 跨平台落地：把钱包能力做成可替换的适配器层

2.1 为什么一定要有适配器层

我见过太多项目把钱包调用直接写进业务代码里：某个按钮的点击回调里直接拼 URI、直接发请求、直接读返回值。这样做的直接后果是，等你哪天要加第二个钱包，或者要从深度链接换成中继会话，就得在整个代码库里搜散落的调用点。更麻烦的是，测试同学没法单独验证钱包链路，因为它是和业务逻辑耦合在一起的。

正确的做法是抽一层钱包适配器，把“连接、签名、断开”这三个动作以及它们对应的事件定义成接口，业务层只依赖接口，不依赖具体实现。这样换实现的时候，业务代码一行都不用改。接口设计上我建议尽量克制，方法不要多，事件要清晰，错误要分类。

interface WalletAdapter { // 发起连接，返回会话对象 connect(options: ConnectOptions): Promise<WalletSession>; // 对消息签名（登录场景） signMessage(session: WalletSession, message: string): Promise<string>; // 对交易结构签名（业务场景） signTransaction(session: WalletSession, tx: TxPayload): Promise<string>; // 主动断开并清理本地状态 disconnect(sessionId: string): Promise<void>; // 事件订阅：账户切换、链切换、会话过期 on(event: WalletEvent, handler: (payload: unknown) => void): void; }

这个接口里有两个设计决定值得说明。第一，连接返回的是会话对象而不是地址。地址只是会话的一个字段，会话还包含 chainId、过期时间、随机数、来源标记。如果只返回地址，你后面做防重放、做多账户隔离时就会发现信息不够用。第二，签名方法必须显式传入 session。这看起来啰嗦，但它强制调用方在签名前确认“我现在用的是哪个会话”，避免了全局单例带来的串号问题——用户切换了账户，你的代码还在拿旧会话签名，这是很典型的事故来源。

适配器层还承担一个隐性职责：统一错误码。深度链接的超时、中继的断线、内嵌 SDK 的用户取消，这些在底层是完全不同的异常类型，但对业务层来说应该只有有限的几种语义：用户取消、连接失败、签名被拒、会话失效、网络异常。把这几种语义定死，业务层的兜底逻辑才能写得干净。

2.2 会话模型：一个容易被做薄的抽象

会话（Session）这个概念在很多实现里被做得很薄，只有一个 sessionId 和一个 address，然后就没了。这是不够的。一个能撑住真实业务的会话对象至少应该包含下面这些字段，而且每个字段都有它存在的理由。

chainId这一项尤其值得强调。多链环境下，同一个地址在不同链上都是合法的，但签名只对特定链有效。如果你的会话里不记录 chainId，用户在钱包里切了链，你这边还在按旧链构造交易，结果就是签名能拿到、但链上验证不通过，报错信息还非常模糊，排查起来能耗掉半天。稳妥的做法是在每次签名前重新比对会话记录的 chainId 与当前业务需要的 chainId，不一致就直接要求重新连接。

nonce的作用是防重放。它不是随便生成的字符串，而是应该由服务端在每次挑战时下发并记录下来，验签时校验这个 nonce 是否被使用过、是否在有效期内。如果 nonce 由客户端生成，攻击者完全可以自己造一个合法的 nonce 去重放旧的签名结果。这一点后面第 4 节还会展开。

2.3 各端的真实差异：别指望一套代码到处跑

跨平台这件事上，最不切实际的期待就是“一套逻辑全平台通吃”。协议层可以统一，唤起层必须分端实现。下面这张表是我在实际项目里总结出来的差异清单，建议在动手前先对着过一遍。

Android 上最典型的问题是进程被回收。用户跳到钱包签名，你这边切到后台，回来的时候 Activity 重建，如果会话状态只存在内存里，那就全丢了。解决办法是把会话的持久化做扎实，至少要落到沙盒存储里，并且在页面初始化时做一次状态恢复。这里有个细节：恢复的时候不能盲目信任本地的过期时间，因为设备时间是可以被用户改的，服务端应该提供一个时间校准或者干脆由服务端判定会话有效性。

iOS 上最常见的是白名单问题。你想检测钱包 App 有没有安装，就需要在配置里声明可查询的 Scheme 列表，没声明的话检测永远返回“未安装”，然后你就走了兜底逻辑，用户一脸懵。这个声明数量还有上限，加起来不要超过 50 个，超了会直接失败。

Web 端最麻烦的是内置浏览器拦截。很多社交类 App 的内置浏览器会把非 http 协议的跳转直接拦掉，连错误回调都不给。这种情况下你只能靠超时来兜底，同时给用户一个明确的引导页，告诉他“请在系统浏览器中打开”。这个引导页的转化率其实不低，关键是文案要直接，别写“当前环境不支持”这种让人摸不着头脑的话。

3. 握手链路拆解：从唤起、授权到会话建立

3.1 唤起参数：拼错一个字符就是半小时的排查

深度链接的唤起本质上就是拼一个 URI，格式大致是scheme://action?param1=xxx&param2=yyy。看起来简单，但真正容易出问题的是参数的编码。待签的消息内容、回跳地址、业务标识，这些参数里都可能包含特殊字符，如果不做严格的 URI 编码，钱包端解析出来的参数就会被截断或者错位。我踩过一次，回跳地址里带了一个没有编码的&，结果回跳时后面半截参数全丢了，日志里看到的回调 URL 是残缺的，查了半天才发现是编码问题。

// 唤起参数拼装的关键点：统一编码 + 显式声明版本 const params = new URLSearchParams({ action: 'connect', chainId: String(chainId), redirect: encodeURIComponent(callbackUrl), nonce: challenge.nonce, v: PROTOCOL_VERSION }); const deeplink = `${WALLET_SCHEME}://${action}?${params.toString()}`;

这里有个实践建议：加一个协议版本参数v。它的作用不是给钱包端看的（钱包端通常不认），而是给你自己看的——当你在日志里发现问题时，能一眼看出是哪个版本的客户端发出的请求。这个字段在灰度期间价值极大。

唤起之后要处理的是超时与兜底。千万不要无限等待。我一般设 15 秒的超时，超时后做两件事：一是把状态恢复成“未连接”，二是给用户一个可点击的“重新尝试”入口。这里不建议超时后自动重试，因为用户可能只是去别的 App 了，自动重试会造成钱包被反复拉起的糟糕体验。

3.2 授权返回后的校验：别拿到地址就直接信

用户授权完成，钱包端会回给你一个地址。很多实现拿到地址就直接存起来当作用户登录成功了，这是非常危险的做法。地址本身不能证明任何事，因为地址是公开信息，任何人都可以把它填到你的回调里。

正确流程是：拿到地址后，服务端下发一段带 nonce 的挑战消息，客户端让用户在钱包里对这段消息签名，签名结果回传服务端，服务端用地址做公钥恢复，验证签名者确实是这个地址，同时校验 nonce 未被使用且在有效期内。只有这三步都过了，才认为“这个用户控制着这个地址”。

{ "address": "0x...", "chainId": 1, "nonce": "b7f3c9a1-...", "issuedAt": 1730000000, "expiresAt": 1730000300, "message": "Sign in to demo-app\nNonce: b7f3c9a1-...\nIssued At: 1730000000" }

这段挑战消息的格式值得讲究一下。消息内容里必须包含域名和应用名，这是为了防钓鱼——用户签名时能在钱包界面看到自己在给哪个应用授权，如果不是他正在用的应用，他会警觉。很多安全事件就是因为挑战消息只有一串随机数，用户根本不知道自己签了什么。

还有几个校验点容易被漏掉。chainId要和会话预期一致，不一致说明用户切了链，需要重新走一遍。expiresAt在服务端校验，不要信客户端传过来的时间。地址要做校验和格式归一化，同一个地址的大小写形式在字符串比较时是不一样的，如果你用字符串相等来判断“是不是同一个用户”，会出现同一用户被识别成两个的情况。

3.3 会话生命周期：过期、切换、断线三件事

会话不是建立完就一劳永逸的。线上跑起来之后，会话相关的故障会占到钱包问题的一半以上。

过期处理上，我建议会话有效期设短一点，比如 24 小时，并且每次签名操作前都做一次有效性检查。别指望“用户不会用太久”，线上真实情况是有人会挂着一个页面放三天。过期后的处理要平滑，不要直接弹一个“会话已失效”然后让用户从头再来，最好是保留用户的业务上下文，只重新走一次授权。

账户切换是最容易出事的。用户在钱包 App 里切了账户，但你的应用完全不知道，下一次签名请求发出去，用户会在钱包里看到一个陌生地址的签名确认页，要么懵，要么拒绝。中继会话和部分 SDK 会推送账户变更事件，你必须监听这个事件并立刻让本地会话失效，同时清掉所有与该地址绑定的本地缓存（比如订单草稿、上一次的授权记录）。如果协议层不提供这个事件，那就只能靠“每次签名前比对地址”来兜底。

断线重连主要影响中继会话。长连接断掉之后，重连时不能直接复用旧的会话 ID，因为中继服务端可能已经把状态清了。稳妥的做法是重连后做一次“会话探测”，确认服务端还认这个会话，不认就走重新连接流程。这里还有个细节：重连要有退避策略，固定间隔重试很容易在中继抖动时形成雪崩。

4. 安全接入的红线：私钥不落地、回调防劫持、交易要能看懂

4.1 私钥与助记词：任何形式的索取都是重大事故

这条线没有讨论空间。你的应用在任何场景下都不应该出现“请输入助记词”“请导入私钥”这样的输入框。一旦出现，无论你的出发点是什么（导入旧账户、恢复钱包、迁移数据），都应该被判定为不可接受的设计。

有些团队会觉得委屈：“我们只是想让用户方便一点。”但真实世界里的攻击者正是利用这一点。钓鱼应用最常见的套路就是做一个和正规产品长得一模一样的页面，弹一个“导入钱包以继续”的框。用户一旦输入，资产立刻被转走，而且你作为开发方会被追究责任。所以这条红线不只是安全问题，也是产品声誉问题。

那本地到底能存什么？能存地址、能存公钥、能存会话标识、能存一些非敏感的偏好设置。不能存任何能推导出私钥的材料，不能存签名结果的明文副本（签名结果本身在有效期内被拿到可以被重放）。存储位置也要挑，Android 用 Keystore 支持的加密存储，iOS 用钥匙串，别一股脑塞进普通的偏好设置里。

还有一点常被忽视：日志。开发阶段为了调试方便，很多人会把完整的请求参数打出来，其中可能包含签名结果。上线前一定要把这块清理干净，签名结果、完整地址、挑战消息原文都不应该进日志和埋点上报。地址要脱敏成前后各保留若干位的形式。

4.2 回调劫持：自定义 Scheme 天生不安全

自定义 URI Scheme 有一个根本性缺陷：它没有唯一性。任何 App 都可以在自己的配置里注册同一个 Scheme，而系统在唤起时的选择是不确定的。这意味着一个恶意应用可以注册和你的产品相同的 Scheme，把回跳参数截走。截走之后它能拿到什么？可能是会话标识、可能是地址、可能是签名结果。

所以只要用深度链接，就必须假设回跳通道是不可信的。防护手段有几层，我建议全上。

第一层，优先使用通用链接或应用链接，这类链接绑定了域名，验证通过后系统会保证只有你的应用能接收。这是最有效的一层，能上就上，别嫌配置麻烦。

第二层，回调参数带一次性令牌。这个令牌是你在发起唤起时生成的，服务端存一份，回调回来时必须带回来，且只能用一次，用完立刻作废。这样即使参数被截走，攻击者也没法用它建立有效会话。

第三层，服务端二次校验。永远不要因为“回调回来了”就认为操作成功。真正的成功判定只有一个：服务端拿到了有效的签名并且验签通过。客户端收到回调只能当作一个“可能完成了”的信号，用来触发查询，而不是直接更新状态。

这三层里，很多团队只做了第三层，觉得服务端验签过了就行。但如果回跳参数被截走，用户那边的体验就是“签完了没反应”，而攻击者那边可能拿到了会话标识去做别的事。所以第一层和第二层不是“锦上添花”，是“补齐短板”。

4.3 交易内容必须让用户看懂

签名交易的场景里，用户看到的确认页是钱包方渲染的。如果你的应用只传一个未解析的 data 字段过去，钱包界面很可能只显示“合约交互”或者干脆只显示一串十六进制，用户根本不知道自己签了什么。这不是钱包的问题，是你没给足信息。

给足信息意味着三件事。第一，把交易的目标地址、金额、Gas 相关参数填清楚，不要留空让它去猜。第二，如果是合约调用，把方法名和关键参数用可读形式标注出来，比如“授权某地址使用你无限额的代币”，而不是让用户面对approve(address,uint256)。

第三，也是最重要的，涉及授权额度的场景一定要给有限额度。无限授权是链上资产损失的头号原因之一。你的产品如果确实需要授权，就设定一个合理的额度上限和有效期，宁可让用户多签几次，也不要为了省事给一个无限额度。这一点在产品需求评审阶段就该定下来，等开发完了再改会很被动。

4.4 风险提示的位置和措辞

风险提示不能只写在用户协议里。用户不会看协议，这是事实。真正有效的提示要出现在决策发生的那一刻，也就是签名确认之前。

我比较推荐的做法是：在应用内发起签名之前，用一段简短的话说明这次操作的后果，比如“本次操作将允许对方转出你账户中的某类资产，额度上限为 X，有效期 30 天”。措辞要具体到动作和数量，避免“请注意风险”这种谁都不会当真的话。这段话不需要很长，两三行足够，但它必须出现在用户点击“确认”之前，而不是之后。

5. 联调排错：把“唤起不了”拆成可复现的检查项

5.1 一张故障树，把玄学变成流程

钱包集成最折磨人的地方在于，失败时往往只有一个“没反应”，没有任何错误信息。这时候如果没有一套结构化的排查方法，很容易陷入“改一行试一次”的低效循环。我自己的做法是把它画成一棵故障树，从上往下逐层排除。

这张表里最值得说的是“验签失败”这一行。验签失败的根因里，消息拼接格式不一致占了大头。客户端签名时用的消息和服务端验签时重建的消息，只要有一个空格、一个换行、一个字段顺序不一样，结果就完全不同。解决方法是把消息模板定义在服务端，客户端只负责填充变量，不要两边各写一套模板。如果非要两边各写，至少加一个“调试模式”把两边的原文都打出来比对。

5.2 真机矩阵：模拟器上通过不等于能用

钱包集成有一个残酷现实：模拟器上的一切都是假的。因为你要唤起的是另一个真实存在的 App，模拟器里没有它。所以从第一天起就必须用真机做验证，而且不能只用一台。

我建议的设备矩阵至少包括：一台主流 Android 机型（系统版本不要太新，代表存量用户）、一台较新的 Android（覆盖新的后台限制策略）、一台 iOS。有条件的话再加一台低端 Android，因为低端机的内存压力会暴露进程被回收的问题——而这恰恰是会话丢失的主要成因。

另外还有一个必测场景：冷启动回跳。流程是先把你的应用完全杀掉，然后再点链接唤起钱包，签完之后看能不能正确回来并恢复状态。这个场景在开发阶段经常被跳过，因为它操作麻烦，但它对应的是真实用户最常见的路径之一。

5.3 上线前的验收清单

下面这份清单是我每次上线前都会过一遍的，基本上能挡住八成以上的线上事故。

• 所有唤起路径在冷启动状态下验证通过，且状态能正确恢复
• 会话过期后，重新授权的流程不会丢失用户业务上下文
• 账户切换事件能正确触发本地会话失效，且清理了相关缓存
• 验签失败时，用户看到的是可理解的提示，不是一串错误码
• 回调参数的一次性令牌被使用后立即失效，重放会被拒绝
• 日志与埋点中不含完整地址、签名结果、挑战消息原文
• 弱网环境下（限速到 2G 级别）整个链路能给出明确的失败提示而不是无限转圈
• 内置浏览器环境有明确的引导页，而不是静默失败
• 协议版本参数已带上，且服务端能识别未知版本并给出可读错误

这份清单里最后一条经常被忽略，但它在灰度期特别有用。当你开始给一部分用户上新版本协议时，如果服务端遇到不认识的版本号能明确报错而不是默默当成老版本处理，问题定位会快很多。

6. 上线之后：版本协商、能力探测与灰度推进

6.1 用能力探测代替版本号硬判断

钱包端的升级节奏你控制不了。今天支持的参数，下个版本可能改了名字；今天没有的能力，下个版本可能加上了。如果你的代码里全是if (version >= 3)这种硬判断，那每次钱包升级你都得到处改条件。

更稳的做法是能力探测：在连接阶段让钱包端（或中继层）返回一份能力清单，比如支持哪些签名类型、支持哪些链、单次会话最长有效期是多久。你的代码根据清单决定走哪条分支，而不是根据版本号猜。这样钱包方新增能力你自动受益，移除能力你也能优雅降级。

{ "capabilities": { "signMessage": true, "signTypedData": true, "chains": [1, 56, 137], "maxSessionTtl": 86400, "supportsAccountSwitchEvent": true } }

这份清单要有缓存策略，但缓存时间不能太长，我一般设 1 小时。太长了钱包升级后你还在用旧能力表，太短了每次都多一次请求。

6.2 灰度：先放量 1%，看这三个指标

新协议或者新路径上线，一定要灰度。放量的判断依据不是“有没有报错”，而是三个成功率指标：唤起成功率、授权成功率、签名成功率。这三个是串联的，前面掉一点，后面就会被放大。

具体来看，唤起成功率低于基线就要停，因为这说明新路径在部分机型上根本起不来；授权成功率掉了说明用户在看到授权页之后放弃了，可能是文案或者展示出了问题；签名成功率掉了则要看是不是参数构造有变化导致钱包端拒绝。这三个指标分开看才有诊断价值，混成一个“整体成功率”是看不出问题的。

灰度期间还要盯一个隐性指标：回调延迟的中位数。这个数字如果明显上升，说明回跳链路变长了或者有重试，虽然最终成功率没掉，但用户体验已经在恶化。

6.3 长期维护里最容易被忽视的一件事

最后说一个不太技术但很实际的问题：域名和路径的稳定性。如果你用了通用链接，那个域名和路径就是你的身份凭证，一旦变更，所有已安装的旧版本都会失效。所以在项目初期选域名的时候就要想清楚，别用一个临时域名上线，后面再迁移的代价非常大。路径也一样，/wallet/callback这种路径定下来就别改了，改一次等于把存量用户全部打断。

我在实际项目里的体会是，钱包集成这件事，真正花时间的从来不是“把链路跑通”，而是“把链路在各种恶劣条件下跑稳”。跑通可能只要两天，跑稳要两个月。这两个月里你会遇到进程被回收、参数被截断、回调被抢、时间被改、账户被切、网络抖动、钱包升级，而这些在文档里一个字都不会提。所以如果你正准备做这件事，我的建议是：先把故障树和验收清单写出来，再动手写代码，顺序反过来会让你多走很多弯路。