<p>最直接官方推荐的C# IPFS客户端是IPFS.HttpClient，需配合启用写权限的节点（如本地go-ipfs或Pinata），上传后须pin固定以保障持久化。</p>
用 IPFS.HttpClient 上传文件最直接
官方推荐的 C# IPFS 客户端是 IPFS.HttpClient（由 ipfs-shipyard 维护），它封装了 HTTP API 调用，不需要本地运行 go-ipfs 进程，只要有个可访问的 IPFS 节点（比如 https://ipfs.io 或自建节点）就能传。
注意：公共网关如 https://ipfs.io 默认只支持 GET，不开放 POST /api/v0/add，所以你得找一个启用了写权限的节点——常见选择是本地运行的 go-ipfs（监听 http://127.0.0.1:5001），或使用 Infura、Pinata 等商业服务提供的 API endpoint 和 API key。
- 安装包：
dotnet add package IPFS.HttpClient - 初始化客户端时传入正确的 base URL，例如
new IpfsClient("http://127.0.0.1:5001") - 若用 Pinata，URL 是
https://api.pinata.cloud/psa，需在请求头加pinata_api_key和pinata_secret_api_key（IPFS.HttpClient不原生支持，得自己扩展HttpClientHandler或换用RestSharp）
AddAsync 上传单个文件要注意流生命周期
调用 AddAsync 时传入 Stream，但这个流必须在上传完成前保持打开状态。常见错误是用 File.OpenRead(path) 后没确保它活到 await 结束，或者在 using 块里提前释放。
正确做法是显式控制流，或改用 AddBytesAsync 处理小文件：
var client = new IpfsClient("http://127.0.0.1:5001");
using var stream = File.OpenRead(@"C:\data\report.pdf");
var result = await client.AddAsync(stream, "report.pdf"); // 注意：文件名只是 hint，不影响内容寻址
Console.WriteLine(result.Hash); // 输出类似 QmVt...- 大文件建议分块读取 + 取消令牌（
cancellationToken参数）防止卡死 -
AddAsync默认把文件包装成 UnixFS 目录结构；如果只想存裸数据（比如一段 JSON），加参数wrapWithDirectory: false - 返回的
Hash是内容唯一标识，不是 URL；要生成可访问链接，拼成https://ipfs.io/ipfs/{hash}或你所用网关的格式
上传失败常见报错和对应解法
遇到 HttpRequestException 或 HTTP 4xx/5xx 是最常卡住的地方，根本原因往往不是代码写错，而是环境配置偏差：
-
Connection refused→ 检查go-ipfs是否运行、API 是否启用（ipfs config Addresses.API应含/ip4/127.0.0.1/tcp/5001）、是否执行过ipfs daemon -
403 Forbidden→ 公共网关拒绝写操作；Infura/Pinata 需确认 API key 有 upload 权限，并在 header 正确设置（Authorization: Bearer xxx或 vendor-specific header） -
413 Payload Too Large→ go-ipfs 默认限制单次上传 100MB；改配置：编辑~/.ipfs/config，在API.HTTPHeaders下加"Access-Control-Max-Age": ["86400"]不起作用，真正要调的是Gateway.HTTPHeaders和重启 daemon；更简单是分片上传或调高MaxBodySize（需编译定制版） - 返回空 hash 或
null→ 检查流是否为空、文件路径是否存在、网络是否拦截了 multipart/form-data 请求
生产环境别跳过内容校验和持久化保障
IPFS 本身不保证文件长期在线——你上传完得到 hash，不代表它明天还能访问。尤其用公共节点上传，内容可能很快被 GC 清掉。
- 上传后立刻用
client.Pin.AddAsync(hash)固定（pin），否则本地节点重启后可能丢失 - 关键业务必须搭配 pinning service（如 Pinata、Web3.Storage），它们提供 SLA 和冗余存储，且返回的 CID 可直接用于生产
- 上传前建议先计算本地文件的 CID（用
IPFS.Core或命令行ipfs add --only-hash），和上传后返回的比对，确认内容没被篡改或截断 - 不要依赖文件名或路径做业务逻辑——IPFS 寻址只认 CID，所有元信息（如原始文件名、MIME 类型）需额外存在链下数据库或用
ipfs dag put存结构化数据
真正麻烦的从来不是“怎么传上去”，而是“怎么确保它一直能被找到”。CID 生成规则、网关可用性、pinning 策略，这三个点漏掉任何一个，上线后都容易变成线上事故。
