梳理 IPFS 在节点、Pinning、Gateway 三层最常见的故障与定位方法，结合 NFT、DApp 与交易所对接的实战经验，给出一份可直接复用的调试 checklist。

IPFS 调试方法：从节点到 Gateway 的全链路排查

IPFS 是 Web3 项目最常用的去中心化存储方案，但「文件传完了为什么前端打不开」「节点跑着却没人拉」这类问题让不少团队头痛。本文按节点 → Pinning → Gateway → 前端四个环节，给出系统化的调试方法。

一、节点层调试

第一步先确认你的 ipfs 节点是否健康。ipfs id 看 peer ID 与监听地址，ipfs swarm peers 看连通 peer 数。peer 数低于 20 就要怀疑网络问题，可能是防火墙没放行 4001 端口，或者你跑在 NAT 后没启用 hole-punching。

若你的项目同时跑了链上业务，建议先把链与存储的资金分开。比如运维 ETH 可以从 Binance官网提到运营钱包，Binance提币选择 ERC20 网络稳定到账。

上传成功不等于持久化。ipfs pin ls 看 CID 是否在 pin 列表里；如果用的是 Pinata、web3.storage 这类托管 Pinning 服务，先在控制台确认状态为 pinned。常见错误是把根目录 pin 了但内层子目录没 pin，导致渲染时随机 404。