Alchemy NFT 元数据旧了或缺图：核对 V3 缓存、原始 URI 与刷新状态
链小知 · 进阶 · 核验 · 依官方文档整理
从已有V3响应定位缓存模式和raw.error，区分元数据、媒体代理及刷新排队；旧V2解析器需要单独迁移。
开始前准备
- 准备已有脱敏的getNFTMetadata请求/响应，包含network host、/nft/v3/路径、contractAddress、tokenId、query与取得时间；没有真实记录时使用官方示例做字段练习。
- 限ERC-721/1155元数据任务，不把Alchemy品牌Solana RPC/DAS套到本EVM REST接口。不运行docs-demo、SDK、认证API或刷新请求。
1. 先检查版本与 NFT 输入
确认已有URL是https://<network>.g.alchemy.com/nft/v3/<已脱敏key>/getNFTMetadata，再核对contractAddress与tokenId。tokenId可十进制或hex，44和0x2c表示同一数；用字符串/大整数比较而不是低精度浮点。tokenType只有确认标准后才填ERC721或ERC1155。
本方法正文列Ethereum和若干L2例子，不代表全部品牌网络支持。若旧文档链接跳V3，只说明文档入口变化，不是已有数据请求已迁移；保留实际请求路径而不是以最终帮助页替代它。
检查结果：网络、V3路径、合约、ID数值和标准是否确认均记录。
2. 根据两个缓存参数判断实际读取模式
记录refreshCache的true/false/省略，以及tokenUriTimeoutInMs的整数或省略。refreshCache默认false会先用cache，cache miss仍可能刷新；false不等于“永远不访问原URI”。
tokenUriTimeoutInMs单位毫秒，0表示仅cache且不为cache miss抓取；默认没有指定超时。1000是1秒，不是1000秒。若两参数组成未明确说明的组合，保留组合和实际响应，不猜服务器的优先顺序。
检查结果：缓存模式与超时单位明确，未知组合没有自动推为最新或不存在。
3. 分别读取 raw、展示媒体与时间字段
在V3示例结构中分开raw.tokenUri、raw.metadata、raw.error、image.originalUrl和image.cachedUrl/thumbnailUrl/pngUrl；保留timeLastUpdated及响应取得时间。原URI或JSON引用不等于CDN展示，CDN仍旧也不能直接证明原项目没更新。
字段缺失/null不补空串或0；timeLastUpdated不是所有权、铸造时间或永久同步完成证据。animation示例出现orginalUrl拼写，固定官方示例又写originalUrl；按实际原响应及已确认版本处理，未拿到时保留字段兼容未知。
检查结果：原始元数据、缓存媒体、错误与时间四层独立，真实字段名可复核。
4. 把 URI 故障与账户限流分开
已有raw.error若是网关timeout或Throttled token URI，先记原元数据站点的故障；FAQ说明后者可能是源站429，不等于Alchemy账户吞吐429。malformed token URI或没有合约代码则回查输入、网络和URI，不盲目重复请求。
FAQ有media.gateway/tokenUri.raw等旧响应字段，不能机械复制到V3。错误处理概念可参考，但解析路径以V3实际响应为准；“token does not exist”也不由一条错误推未铸造或资产消失的完整结论。
检查结果：源站错误、参数/网络错误、账户错误分别保留，未用旧字段覆盖V3。
5. 已有刷新回执只按其状态与网络解读
refreshNftMetadata是POST提交刷新，官方200示例status=Queued、estimatedMsToRefresh=10000：这是预计10秒，不是10000秒、保证延迟或已完成。若后续同资产响应确实改变，再保留新旧字段与读取时间对照。
该刷新端点正文只列Ethereum主网/Sepolia、Polygon主网/Amoy、Arbitrum/OP Mainnet/Base主网。其余网络的refreshCache=true建议必须以getNFTMetadata在该链可用为前提，不能把GET支持矩阵原封不动当POST支持。
检查结果：回执、估计时间与实际更新分开；刷新网络范围单独检查。
6. 把旧 V2 解析与已退役方法从诊断中移出
固定官方2026-08-26迁移说明写V2→V3响应形状变化，例如title→name、image.cachedUrl；本轮旧V2文档入口重定向到V3。对已有旧记录先保留原版本，再修改解析方案；未调用数据接口确认旧URL的301或兼容。
2026-08-18公告计划9月30移除一组冗余方法，invalidateContract在列而refreshNftMetadata保留；当前目录也列getNFTMetadata。不要为了处理缺图调用旧invalidateContract，或将“文档仍可找到”当当前服务证明。
检查结果：诊断包含版本、缓存、媒体/URI错误、刷新范围和仍待实际验收项。
怎样确认完成
- 已有记录可归入输入/解析、缓存、源站URI或刷新待完成问题，未知项保留。
- 依据当前文档与固定官方说明整理；没有目标NFT、live/cache miss、V2业务重定向或刷新完成实测。
常见错误与边界
- metadata与image缓存不是同一层；false并不总是纯cache。
- 元数据缺项不能推没有所有权，代理图片也不是原始存储证明。
- 旧官方资料仍有未来式及迁移替代差异；只采用明确适用的版本事实，不声称现行API已实测。