第13章：基本文件操作

所属部分：第四部分：实践操作指南

13.1 添加文件到IPFS

将文件添加到IPFS，本质上是执行内容寻址哈希计算与分布式存储协同的过程。ipfs add 命令并非传统意义上的“上传”（即向中心化服务器发送副本），而是完成以下关键步骤： ① 按分块策略对文件内容进行切分（默认使用 --chunker=size-262144，即 256 KiB）； ② 对每个数据块独立计算 sha2-256 哈希值，生成唯一的内容标识符（CID，Content Identifier）； ③ 构建有向无环图（DAG），其中根节点对应整个文件或目录的 CID； ④ 将所有数据块及其 DAG 节点写入本地 IPFS 仓库（路径为 ~/.ipfs/blocks/），并将其 CID 广播至分布式哈希表（DHT）网络，供其他节点发现和获取。

💡 提示：CID 是内容的“指纹”，而非位置标识。只要内容不变，无论在何处、何时添加，生成的 CID 始终一致——这是 IPFS 实现内容寻址与去中心化共享的核心基础。

⚠️ 注意：ipfs add 默认仅将数据写入本地节点仓库，不会自动向全网“发布”或“固定”（pin）该内容。若希望确保文件长期可访问，需后续执行 ipfs pin add 或启用自动固定策略。

基础用法示例：

# 添加单个文件，输出其 CID（v1 格式，默认 base32 编码）
$ ipfs add report.pdf
added bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi report.pdf
1.01 MiB / 1.01 MiB [=====================================] 100.00% 2.42 MiB/s

# 添加时显式指定 CID 版本、哈希算法与分块大小（推荐 v1 + sha2-256 + 合理 chunker，兼顾兼容性、安全性和性能）
$ ipfs add --cid-version=1 --hash=sha2-256 --chunker=size-1048576 report.pdf
added bafybeih2k7ajd4x2j3h6p5t7q9r8s1u2v3w4x5y6z7a8b9c0d1e2f3g4h5i6j7k8l9m0n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5m6n7o8p9q0r1s2t3u4v5w6x7y8z9a0b1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x3y4z5a6b7c8d9e0f1g2h3i4j5k6l7m8n9o0p1q2r3s4t5u6v7w8x9y0z1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7a8b9c0d1e2f3g4h5i6j7k8l9m0n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5m6n7o8p9q0r1s2t3u4v5w6x7y8z9a0b1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x3y4z5a6b7c8d9e0f1g2h3i4j5k6l7m8n9o0p1q2r3s4t5u6v7w8x9y0z1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7a8b9c0d1e2f3g4h5i6j7k8l9m0n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5m6n7o8p9q0r1s2t3u4v5w6x7y8z9a0b1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x3y4z5a6b7c8d9e0f1g2h3i4j5k6l7m8n9o0p1q2r3s4t5u6v7w8x9y0z1a2b3c4d5e6f report.pdf

⚠️ 注意：第二个示例中展示的 CID 过长，是因刻意设置极大分块（size-1048576）后仍保留完整输出所致。实际使用中，不建议盲目增大分块尺寸：过大的块会降低内容复用率（如两个相似文件的微小差异可能导致全部块哈希不同），并影响流式加载与随机访问效率。常规场景下，保持默认 256 KiB 或根据具体需求设为 512 KiB～1 MiB 更为合理。