用 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 策略，这三个点漏掉任何一个，上线后都容易变成线上事故。
