企业官网建设流程全解析

• 存储
• 网络
• 通信

js-IPFS 使用 IPLD（InterPlanetary Linked Data）作为其内容寻址数据模型，仓库中的每个数据块都对应一个 CID 和一段字节数据，而解码这些字节数据必须依赖对应的 BlockCodec。本文以仓库文档 docs/IPLD.md 为核心骨架，系统讲解 js-IPFS 内置的 BlockCodecs、Multihashes、Multibases，并给出在进程内节点与 HTTP API Client 两端扩展自定义编解码器的完整配置方案。读完本文，你将掌握 CID 编解码机制、内置格式清单，以及通过ipld配置项接入自定义 codec / hasher / base 的实战方法。

Overview：CID、字节块与 BlockCodec 的关系

IPFS 仓库（repo）内部持有一个 blockstore，用来存放构成 IPFS 网络上文件的所有数据块（block）。每个块在概念上可以看作一个CID 与一段字节数组（byte array）的配对：CID 负责标识内容，字节数组负责承载内容本身。

CID 中携带一个code属性，它告诉我们如何解读与该 CID 关联的字节数组——例如某段字节应当被解析为 protobuf 格式的文件目录，还是被解析为 JSON 对象。要完成这种"解读"，就必须加载一个与该code值对应的 BlockCodec（区块编解码器）。

同理，Multihash（哈希函数）与 Multibase（基编码）的实现也必须可用，才能正确计算内容标识、并对外展示或解析 CID 字符串。也就是说，编解码器、哈希器、基编码这三类实现共同构成了 js-IPFS 读写 IPLD 数据的基础设施。

在 js-IPFS 的源码中，这套基础设施在节点启动时被统一组装。以 packages/ipfs-core/src/components/index.js 为例，节点会把内置 codecs、用户通过options.ipld.codecs传入的 codec，以及loadCodec动态加载函数一起交给Multicodecs实例管理；bases、hashers也以同样方式组装（见同文件第 90-104 行）。HTTP Client 的组装逻辑与之完全对应（见 packages/ipfs-http-client/src/index.js），这是下文"双端配置"的关键所在。

内置 BlockCodecs

js-IPFS 随包内置了若干编解码器，其中四个是创建和解读 UnixFS 结构所必需的：

1. @ipld/dag-pb：用于文件和目录结构。UnixFS 的 protobuf 格式块都由它编解码，是add、ls、cat等文件操作的基础。
2. raw：用于文件数据，当以--raw-leaves=true（原始叶子节点）导入文件时，叶子数据块直接使用 raw codec，不再包裹 UnixFS protobuf 头。
3. @ipld/dag-cbor：用于存储带 CID 链接的 JavaScript 对象，支持在对象中内嵌指向其他块的 CID，从而构造任意 DAG 图。
4. json：用于存储纯 JavaScript 对象（不含 CID 链接的普通 JSON 数据）。

从源码看，实际内置的集合比这四者更宽。在 packages/ipfs-core/src/components/index.js 中，节点启动时会把multiformats/basics导出的全部 codecs、dag-pb、dag-cbor、dag-json、dag-jose以及 identity codec 一并注册，再拼接用户自定义 codec。换言之，上表四个是官方文档强调的"UnixFS 必需项"，而真实环境还额外具备dag-json、dag-jose等能力。

内置 Multihashes

js-IPFS 内置了 js-multiformats 导出的全部多哈希（multihash）实现，其中就包括最常用的sha2-256，以及sha2-512、sha3-*、blake2b-*、identity等。sha2-256也是 js-IPFS 的默认哈希，绝大多数 CIDv1 内容标识都基于它生成。

从 packages/ipfs-core/src/components/index.js 可以看出，节点内置 hashers 来自multiformats/basics的hashes导出，用户额外指定的 hashers 会追加到同一列表中，最终统一交给Multihashes实例（见 packages/ipfs-core-utils/src/multihashes.js）。

如果应用需要使用内置之外的哈希函数，可以通过hashers配置属性追加自定义实现（详见下文"添加额外的编解码器、哈希器与基编码"一节）。

内置 Multibases

与 Multihash 类似，js-IPFS 也内置了 js-multiformats 导出的全部多基编码（multibase）实现，包括：

• base58btc：默认的 CID 字符串展示形式（如Qm...开头的 CIDv0 即 base58btc 编码）；
• base32：CIDv1 默认使用的基编码（小写、无填充，形如bafy...即base32前缀为b）；
• 以及base16（hex）、base64、base36、base58flickr、base32hex、base32z、base64url等。

用户可通过bases配置属性追加额外的基编码。在 packages/ipfs-core/src/components/index.js 中，内置 bases 与自定义 bases 会被合并后交给Multibases实例；其实现类见 packages/ipfs-core-utils/src/multibases.js，它同时维护了"按名称"与"按前缀字符"两套查找索引。

添加额外的 BlockCodecs、Multihashes 与 Multibases

如果应用需要支持额外格式（例如读取 git 仓库对象、bitcoin 交易等特殊数据），就需要在两个位置分别配置，二者缺一不可：

• IPFS 节点侧：让节点知道如何把收到的数据交给 IPLD 进行序列化/反序列化；
• HTTP API Client 侧：让客户端能通过 HTTP 把数据正确地发送给节点。

下面的配置代码就是官方文档给出的推荐写法，两类创建入口结构完全一致。

1. 配置 IPFS 节点的 IPLD 层

以进程内节点为例，配置options.ipld即可：

import { create } from 'ipfs' import customBlockCodec from 'custom-blockcodec' import customMultibase from 'custom-multibase' import customMultihasher from 'custom-multihasher' const node = await create({ ipld: { // 方式一：把 BlockCodec 直接加入 codecs 列表 codecs: [ customBlockCodec ], // 方式二：提供函数按名称/代码动态加载 codec loadCodec: async (codecNameOrCode) => { return import(codecNameOrCode) }, // 方式一：把 Multibase 加入 bases 列表 bases: [ customMultibase ], // 方式二：动态加载 base loadBase: async (baseNameOrCode) => { return import(baseNameOrCode) }, // 方式一：把 Multihash hasher 加入 hashers 列表 hashers: [ customMultihasher ], // 方式二：动态加载 hasher loadHasher: async (hashNameOrCode) => { return import(hashNameOrCode) } } })

"列表 + 动态加载函数"双通道设计：codecs/bases/hashers列表用于静态注册明确已知的实现；loadCodec/loadBase/loadHasher用于按需动态解析——当遇到列表中未注册、但按名称或代码标识可以加载的实现时，节点会调用这些函数。若未提供加载函数，底层会使用默认的拒绝逻辑：Multicodecs/Multibases/Multihashes类的默认 loader 会直接抛出No codec found for "..."/No base found for "..."/No hasher found for "..."错误（见 packages/ipfs-core-utils/src/multicodecs.js、packages/ipfs-core-utils/src/multibases.js、packages/ipfs-core-utils/src/multihashes.js）。

需要指出的是：该ipld配置对象会与默认配置合并而非整体替换，具体约定见 docs/MODULE.md 的options.ipld小节。浏览器端的默认 IPLD 格式集合更精简（默认只含dag-pb、dag-cbor、raw等），因此浏览器场景下自定义配置的需求更常见。

2. 配置 IPFS HTTP API Client

客户端侧采用同样的ipld配置结构，只是入口函数来自ipfs-http-client：

import { create } from 'ipfs-http-client' import customBlockCodec from 'custom-blockcodec' import customMultibase from 'custom-multibase' import customMultihasher from 'custom-multihasher' const client = create({ url: 'http://127.0.0.1:5002', ipld: { // 方式一：直接注册 BlockCodec codecs: [ customBlockCodec ], // 方式二：动态加载 loadCodec: async (codecNameOrCode) => { return import(codecNameOrCode) }, // 方式一：直接注册 Multibase bases: [ customMultibase ], // 方式二：动态加载 loadBase: async (baseNameOrCode) => { return import(baseNameOrCode) }, // 方式一：直接注册 Multihash hasher hashers: [ customMultihasher ], // 方式二：动态加载 loadHasher: async (hashNameOrCode) => { return import(hashNameOrCode) } } })

示例中的http://127.0.0.1:5002正是 js-IPFS 默认的 API 监听地址：默认配置中Addresses.API即为/ip4/127.0.0.1/tcp/5002（见 packages/ipfs-core-config/src/config.js），与文档示例完全一致。从源码看，HTTP 客户端在 packages/ipfs-http-client/src/index.js 中以与节点侧几乎相同的逻辑组装Multibases、Multicodecs、Multihashes，并把这些能力注入dag、object、refs等 API 实现。

为什么节点与客户端都要配置？

这两处配置承担的是不同职责：

• 节点侧配置负责"解码与解释"：节点需要能解析收到的数据、把原始字节按其 code 还原为结构化对象（如 UnixFS 目录、DAG-CBOR 对象），这依赖于注册在节点上的 codec。
• 客户端侧配置负责"编码与发送"：客户端需要把应用层的数据（如dag.put传入的对象）编码成正确的字节格式，并通过 HTTP 传输给节点；若客户端缺少对应 codec，就无法完成序列化。

两者各司其职，因此新增自定义格式时必须两端同时配置，否则会出现"节点能读但客户端不能写"或反之的割裂问题。

兼容旧版 IPLD format 的迁移路径

对于尚未迁移到新 BlockCodec 接口的旧式 IPLD format（例如ipld-git、ipld-bitcoin等），社区提供了ipld-format-to-blockcodec模块做桥接转换，把旧的 format 包装成新的 BlockCodec 再注册。这一用法在 docs/MODULE.md 的options.ipld章节中有完整示例：通过convert(ipldGit)将旧 format 转换为 BlockCodec 后放入codecs列表即可。此外，动态加载（loadCodec）还支持浏览器环境的import()动态导入与 Webpack 魔法注释分包，让自定义格式在浏览器端也能按需加载。

Next steps：可运行的示例与进一步探索

如果你想看到上述配置的完整可运行代码，官方维护的示例仓库提供了两个高价值参考：

• custom-ipld-formats 示例：分别演示了"进程内 IPFS 节点"、"以 daemon 方式运行的 IPFS"以及"HTTP 客户端"三种场景下接入自定义 IPLD 格式的完整代码；
• traverse-ipld-graphs 示例：演示如何遍历 IPLD 图，并结合ipld-format-to-blockcodec使用尚未移植到新 BlockCodec 接口的旧 IPLD format，同时展示如何挂载额外的 Multihash Hasher。

在仓库内，你也可以直接阅读以下源码与文档深化理解：

• packages/ipfs-core/src/components/index.js：节点侧 codec / hasher / base 的组装逻辑；
• packages/ipfs-http-client/src/index.js：HTTP 客户端侧的同构组装逻辑；
• packages/ipfs-core-utils/src/multicodecs.js、packages/ipfs-core-utils/src/multibases.js、packages/ipfs-core-utils/src/multihashes.js：三类注册表实现，含默认 loader 的报错行为；
• docs/MODULE.md：options.ipld的完整配置说明与旧 format 迁移示例；
• docs/core-api/DAG.md：DAG API 的日常使用方式，配合自定义 codec 可读写任意 IPLD 数据。

• 存储
• 网络
• 通信