Veramo DID 解析返回空文档：检查 resolver、元数据和密钥用途
链小知 · 进阶 · 核验 · 依官方文档整理
以已有 DID 解析结果定位插件缺失与 fragment 问题，并避免把 DID 解析成功当身份或凭证事实验证。
开始前准备
- 准备已配置 Veramo Agent 的依赖版本、公开 DID URL 与脱敏 DIDResolutionResult/错误记录。
- API 文档显示 v7.0.0，官方 Introduction 仍有 public beta 提示；项目应按实际安装版本核对。只处理现有 DID，不创建身份、签名或调用付费 resolver。
1. 确认配置了对应 DID method
先识别输入前缀 did:<method>:…，再检查 Agent 的 DIDResolverPlugin。插件构造需要 Resolvable 或 method 到 DIDResolver 的映射；空配置会出现 invalid_setup。安装 did-manager/身份 provider 不能代替 resolver 配置，读 DID 文档与管理私钥属于不同能力。
检查结果：方法前缀与 resolver 映射一致，插件初始化没有失败。
2. 用 didUrl 调用并等待完整结果
接口形如 await agent.resolveDid({didUrl:"<完整DID>"})，返回 DIDResolutionResult 而非文档本身。官方 Ganache 示例含网络标识；照抄示例地址不代表你的 DID 属于该网络。保留完整方法标识、输入和调用时间，不把省略的 DID 改写成另一种 method。
检查结果：输入 didUrl 与响应对应；已等待 Promise，没有将外层 result 当 didDocument。
3. 先看解析元数据和 null
分别检查 didResolutionMetadata.error、didDocument、didDocumentMetadata。resolver 会补齐缺失字段，didDocument 的默认值是 null；即使对象包含三类字段，也可能解析失败。按返回错误检查 method 配置或读取服务状态，异常与 null 都不能兜底成一份空的成功文档。
检查结果：失败原因、文档为空和成功文档三种结果清楚区分。
4. 核对文档身份与引用用途
有文档时核对 id、controller、verificationMethod，以及 authentication/assertionMethod 的引用。官方示例 blockchainAccountId 为 eip155:1337:…，这个 Ganache 标识不能当 Ethereum 主网地址证明。若准备用某个 key 验证凭证，应检查它是否被相应用途引用，而非仅存在于 verificationMethod。
检查结果：文档 id 与查询相符；目标密钥的用途引用和网络方法标识可回查。
5. 按 section 找 fragment 并限定结论
可调用 getDIDComponentById({didDocument, didUrl:"<DID>#<key-id>", section:"assertionMethod"}) 查相应用途的组件；当前源码支持相对 fragment，找不到会抛 not_found。没有合适的引用应回查文档版本与 key-id，不能静默使用另一个 key。成功解析只提供方法定义的文档，凭证签名/状态/信任仍要相应验证流程。
检查结果：组件存在与用途匹配；结论只写解析和引用结果，不宣称自然人身份或凭证内容真实。
怎样确认完成
- 保存 method/resolver 配置、完整输入、三类响应字段和目标组件用途。
- 本文为文档与官方源码核对，没有真实 DID 查询、签名或凭证验证结果。
常见错误与边界
- Resolver 可以访问特定外部协议；DID method 不等于网站网络筛选里的主网名字。
- didDocument 为 null 仍可能伴随完整外层对象，不能仅检查对象是否存在。
- next 分支源码是排查参考，应与安装版本比较；fragment 解析不是凭证验签。