# Veramo DID 解析返回空文档：检查 resolver、元数据和密钥用途

整理：链小知（AI 辅助）
资料核对日期：2026-10-12
引用地址：https://lianxiaozhi.com/tools/guides/veramo-did-resolution-result
难度：进阶
核验方式：官方文档整理，未执行真实账户操作

以已有 DID 解析结果定位插件缺失与 fragment 问题，并避免把 DID 解析成功当身份或凭证事实验证。

## 使用工具
- [Veramo](https://lianxiaozhi.com/tools/veramo) · [官方入口](https://veramo.io/)

## 前置条件
- 准备已配置 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 映射一致，插件初始化没有失败。
依据：[Veramo v7.0.0 文档：DIDResolverPlugin](https://veramo.io/docs/api/did-resolver.didresolverplugin/)
依据：[Veramo：当前 resolver 实现与缺失 fragment](https://raw.githubusercontent.com/decentralized-identity/veramo/next/packages/did-resolver/src/resolver.ts)
依据：[Veramo：框架定位与公开 beta 提示](https://veramo.io/docs/basics/introduction/)

## 2. 用 didUrl 调用并等待完整结果

接口形如 await agent.resolveDid({didUrl:"<完整DID>"})，返回 DIDResolutionResult 而非文档本身。官方 Ganache 示例含网络标识；照抄示例地址不代表你的 DID 属于该网络。保留完整方法标识、输入和调用时间，不把省略的 DID 改写成另一种 method。

核对结果：输入 didUrl 与响应对应；已等待 Promise，没有将外层 result 当 didDocument。
依据：[Veramo：resolveDid 输入与结果](https://veramo.io/docs/api/core-types.iresolver.resolvedid/)

## 3. 先看解析元数据和 null

分别检查 didResolutionMetadata.error、didDocument、didDocumentMetadata。resolver 会补齐缺失字段，didDocument 的默认值是 null；即使对象包含三类字段，也可能解析失败。按返回错误检查 method 配置或读取服务状态，异常与 null 都不能兜底成一份空的成功文档。

核对结果：失败原因、文档为空和成功文档三种结果清楚区分。
依据：[Veramo：当前 resolver 实现与缺失 fragment](https://raw.githubusercontent.com/decentralized-identity/veramo/next/packages/did-resolver/src/resolver.ts)
依据：[Veramo v7.0.0 文档：DIDResolverPlugin](https://veramo.io/docs/api/did-resolver.didresolverplugin/)

## 4. 核对文档身份与引用用途

有文档时核对 id、controller、verificationMethod，以及 authentication/assertionMethod 的引用。官方示例 blockchainAccountId 为 eip155:1337:…，这个 Ganache 标识不能当 Ethereum 主网地址证明。若准备用某个 key 验证凭证，应检查它是否被相应用途引用，而非仅存在于 verificationMethod。

核对结果：文档 id 与查询相符；目标密钥的用途引用和网络方法标识可回查。
依据：[Veramo：resolveDid 输入与结果](https://veramo.io/docs/api/core-types.iresolver.resolvedid/)
依据：[Veramo v7.0.0 文档：DIDResolverPlugin](https://veramo.io/docs/api/did-resolver.didresolverplugin/)

## 5. 按 section 找 fragment 并限定结论

可调用 getDIDComponentById({didDocument, didUrl:"<DID>#<key-id>", section:"assertionMethod"}) 查相应用途的组件；当前源码支持相对 fragment，找不到会抛 not_found。没有合适的引用应回查文档版本与 key-id，不能静默使用另一个 key。成功解析只提供方法定义的文档，凭证签名/状态/信任仍要相应验证流程。

核对结果：组件存在与用途匹配；结论只写解析和引用结果，不宣称自然人身份或凭证内容真实。
依据：[Veramo：当前 resolver 实现与缺失 fragment](https://raw.githubusercontent.com/decentralized-identity/veramo/next/packages/did-resolver/src/resolver.ts)
依据：[Veramo v7.0.0 文档：DIDResolverPlugin](https://veramo.io/docs/api/did-resolver.didresolverplugin/)

## 常见错误
- Resolver 可以访问特定外部协议；DID method 不等于网站网络筛选里的主网名字。
- didDocument 为 null 仍可能伴随完整外层对象，不能仅检查对象是否存在。
- next 分支源码是排查参考，应与安装版本比较；fragment 解析不是凭证验签。

## 完成检查
- 保存 method/resolver 配置、完整输入、三类响应字段和目标组件用途。
- 本文为文档与官方源码核对，没有真实 DID 查询、签名或凭证验证结果。

## 相关知识

## 官方依据
- [Veramo v7.0.0 文档：DIDResolverPlugin](https://veramo.io/docs/api/did-resolver.didresolverplugin/)
- [Veramo：当前 resolver 实现与缺失 fragment](https://raw.githubusercontent.com/decentralized-identity/veramo/next/packages/did-resolver/src/resolver.ts)
- [Veramo：框架定位与公开 beta 提示](https://veramo.io/docs/basics/introduction/)
- [Veramo：resolveDid 输入与结果](https://veramo.io/docs/api/core-types.iresolver.resolvedid/)