CIDs IPFS 2026: Guia d'adreçament per contingut

Guia pràctica dels CIDs d'IPFS: CIDv0 vs CIDv1, adreçament per contingut, generar CIDs amb Node.js i Python, i verificar la integritat. Actualitzat 2026.

Nacho Collper Actualitzat: 11 min de lectura
Guia pràctica dels CIDs d'IPFS: CIDv0 vs CIDv1, adreçament per contingut, generar CIDs amb Node.js i Python, i verificar la integritat. Actualitzat 2026.
TL;DR
  • Genera un CID reproduïble a partir dels bytes de qualsevol fitxer — el mateix contingut sempre produeix el mateix hash.
  • Utilitza CIDv1 per a les pujades noves: és Base32, en minúscules, i funciona amb gateways de subdomini; CIDv0 no.
  • Un sol byte canviat en un fitxer canvia completament el seu CID, fent que la manipulació sigui detectable a l'instant.
  • L'adreçament per contingut significa que els fitxers s'identifiquen pel que són, no per on estan allotjats.

Si alguna vegada has treballat amb IPFS (InterPlanetary File System), probablement t’has trobat amb cadenes com QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG o bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. No són galimatieso aleatori — són Content Identifiers (CIDs), la columna vertebral del sistema d’adreçament de contingut d’IPFS.

Entendre els CIDs és crucial per a qualsevol que construeixi sobre IPFS, tant si pugues fitxers, com si construeixes aplicacions descentralitzades o implementes sistemes de distribució de contingut. Aquesta guia desglossarà tot el que necessites saber sobre els CIDs d’IPFS, com funciona l’adreçament de contingut i com començar a utilitzar-los en els teus projectes.

Genera un CID en 5 línies (Python)#

import hashlib, base58

def cidv0(content: bytes) -> str:
    sha256 = hashlib.sha256(content).digest()
    return base58.b58encode(b"\x12\x20" + sha256).decode()

print(cidv0(b"hello world"))
# QmaozNR7DZHQK1ZcU9p7QdrshMvXqWK6gpvBw3cWE69N3T

Qualsevol pot reproduir aquest CID — torna a executar-lo amb els mateixos bytes a qualsevol lloc del món i obtindràs la mateixa cadena. Això és l’adreçament de contingut.

Equivalent en Node.js:

import { sha256 } from 'multiformats/hashes/sha2';
import { CID } from 'multiformats/cid';

const bytes = new TextEncoder().encode('hello world');
const hash = await sha256.digest(bytes);
const cid = CID.create(1, 0x55, hash); // version 1, raw codec
console.log(cid.toString());
// bafkreif7l7mvyofhyo6fgs6mjf5gguvm5jcahzgvfb3o7t5lmhz3...
IPFS Ninja

Què és un IPFS CID?#

Un Content Identifier (CID) és una empremta digital única que representa un fragment de contingut a IPFS. A diferència de les URL web tradicionals que apunten a una ubicació (com https://example.com/file.pdf), els CIDs apunten al contingut mateix, independentment d’on estigui emmagatzemat.

Pensa-ho així:

  • Adreçament basat en la ubicació: «Vés al carrer Major 123 i demana el llibre vermell»
  • Adreçament basat en el contingut: «Troba el llibre amb ISBN 978-0-123456-78-9» (no importa quina biblioteca el tingui)

Els CIDs funcionen de manera similar — identifiquen contingut basat en el seu hash criptogràfic, fent el contingut immutable i verificable. Si canvia un sol byte al fitxer, el CID canvia completament.

Per què importa l’adreçament de contingut#

L’arquitectura web tradicional es basa en l’adreçament basat en la ubicació. Quan visites https://example.com/image.jpg, confies en que:

  1. El propietari del domini no ha canviat el contingut
  2. El servidor està en línia i accessible
  3. El contingut no ha estat manipulat

Amb l’adreçament de contingut utilitzant CIDs:

  1. Immutabilitat: El CID garanteix que el contingut no ha canviat
  2. Descentralització: El contingut es pot recuperar des de qualsevol node IPFS que el tingui
  3. Verificació: Pots verificar criptogràficament que has rebut el contingut correcte
  4. Eficiència: El contingut idèntic es deduplica automàticament

Anatomia d’un CID#

Desglossem un CID típic per entendre els seus components:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Hash del contingut (Base32 codificat)
  └─ Prefix Multibase (indica codificació)

Un CID conté diverses peces d’informació:

1. Prefix Multibase#

El primer caràcter indica com està codificat el CID:

  • Q = Codificació Base58 (CIDv0)
  • b = Codificació Base32 (CIDv1)
  • f = Base16/hexadecimal (CIDv1)
  • z = Base58 (CIDv1)

2. Versió CID#

  • CIDv0: Sempre comença amb Qm, utilitza SHA-256, limitat al codec DAG-PB
  • CIDv1: Més flexible, suporta múltiples funcions de hash i codecs

3. Multicodec#

Especifica com s’estructura el contingut (DAG-PB, DAG-CBOR, bytes en cru, etc.)

4. Multihash#

El hash criptogràfic real del contingut, inclòs:

  • Identificador de la funció de hash (generalment SHA-256)
  • Longitud del hash
  • El digest del hash

CIDv0 vs CIDv1: Entenent les diferències#

IPFS ha evolucionat a través de dues versions principals de CID, cadascuna amb característiques distintives:

CIDv0: El format original#

Els CIDs CIDv0 sempre comencen amb Qm i tenen aquest aspecte:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Característiques:

  • Només codificació Base58
  • Només funció de hash SHA-256
  • Només codec DAG-PB (Protobuf)
  • 46 caràcters de longitud
  • Compatible amb totes les implementacions IPFS

Quan utilitzar CIDv0:

  • Màxima compatibilitat amb nodes IPFS més antics
  • Treballar amb sistemes existents que esperen prefixos Qm
  • Emmagatzematge de fitxers (cas d’ús més comú)

CIDv1: L’estàndard modern#

Els CIDs CIDv1 són més flexibles i poden semblar així:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi  # Base32
zb2rhj7crUKTQYRGCRATFaQ6YFLTde2YzdqbbhAASkL9uRDXn      # Base58
f01551220d1e2c35...                                      # Base16

Característiques:

  • Múltiples formats de codificació (Base32, Base58, Base16)
  • Suport per a diferents funcions de hash (SHA-256, SHA-512, BLAKE2, etc.)
  • Múltiples codecs (Raw, DAG-CBOR, DAG-JSON, etc.)
  • Format autodescriptiu
  • Insensible a majúscules en utilitzar Base32

Quan utilitzar CIDv1:

  • Construir noves aplicacions
  • Necessitar identificadors insensibles a majúscules
  • Treballar amb dades estructurades (JSON, CBOR)
  • Utilitzar funcions de hash alternatives

Convertir entre versions#

Pots convertir CIDs entre versions mantenint la mateixa referència de contingut:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

// Convert to CIDv1 Base32
const cidv1 = "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi";

// Both reference the same content!

Com funciona l’adreçament de contingut#

L’adreçament de contingut a IPFS segueix un procés determinista que assegura que el mateix contingut sempre produeix el mateix CID:

1. Preparació del contingut#

Quan afegeixes contingut a IPFS, primer es descompon:

  • Fitxers petits: Emmagatzemats com a blocs únics
  • Fitxers grans: Dividits en trossos i organitzats en un Merkle DAG (graf acíclic dirigit)
  • Directoris: Representats com a estructures DAG que enllacen amb fitxers

2. Procés de hashing#

Cada fragment de contingut passa per:

  1. Serialització: El contingut es formata segons el seu codec
  2. Hashing: Una funció de hash criptogràfica processa les dades serialitzades
  3. Creació de Multihash: El hash s’envolca amb informació d’algoritme i longitud
  4. Acoblament del CID: La versió, el codec i el multihash es combinen

3. Estructura Merkle DAG#

IPFS organitza el contingut en un Merkle DAG on:

  • Cada node té un CID
  • Els nodes pares fan referència als nodes fills via CID
  • Els canvis en qualsevol node es propaguen per l’arbre
  • Estructures senceres es poden verificar criptogràficament
Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Exemples pràctics: Treballant amb CIDs#

Explorem com treballar amb CIDs a la pràctica utilitzant l’API d’IPFS Ninja:

Pujar contingut i obtenir un CID#

// Upload a file and get its CID
const uploadFile = async (content, filename) => {
  const response = await fetch('https://api.ipfs.ninja/upload/new', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bws_1234567890abcdef1234567890abcdef12345678',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content: btoa(content), // Base64 encode binary content
      description: `Upload of ${filename}`
    })
  });
  
  const result = await response.json();
  console.log('CID:', result.cid);
  console.log('IPFS URL:', result.uris.ipfs);
  console.log('HTTP URL:', result.uris.url);
  
  return result.cid;
};

// Example usage
uploadFile('Hello, IPFS!', 'greeting.txt');
// Returns: bafkreifjxz6zwqh27k5xnr5qfbx4w6n5vuwwwdcngguwjewzj2e3xxfgvi

Fixar contingut existent per CID#

Si ja tens un CID, pots fixar-lo per garantir la disponibilitat:

const pinByCID = async (cid) => {
  const response = await fetch('https://api.ipfs.ninja/pin', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bws_1234567890abcdef1234567890abcdef12345678',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      cid: cid,
      description: 'Pinned via API'
    })
  });
  
  const result = await response.json();
  console.log('Pinned CID:', result.cid);
  
  return result;
};

// Pin the "Hello World" of IPFS
pinByCID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u');

Accedir al contingut via CID#

Un cop tens un CID, pots accedir al contingut mitjançant diferents mètodes:

// Direct IPFS gateway access
const ipfsUrl = `https://ipfs.ninja/ipfs/${cid}`;

// Custom gateway (if configured)
const customGatewayUrl = `https://my-app.gw.ipfs.ninja/ipfs/${cid}`;

// Fetch content programmatically
const fetchContent = async (cid) => {
  const response = await fetch(`https://ipfs.ninja/ipfs/${cid}`);
  const content = await response.text();
  return content;
};

Bones pràctiques de CID per a desenvolupadors#

1. Valida sempre els CIDs#

Abans d’utilitzar un CID a la teva aplicació, valida el seu format:

const isValidCID = (cid) => {
  // Basic validation patterns
  const cidv0Pattern = /^Qm[1-9A-HJ-NP-Za-km-z]{44}$/;
  const cidv1Pattern = /^[bf][a-z2-7]{58}$/;
  
  return cidv0Pattern.test(cid) || cidv1Pattern.test(cid);
};

2. Gestiona ambdues versions de CID#

La teva aplicació hauria de funcionar tant amb CIDv0 com amb CIDv1:

const normalizeCID = (cid) => {
  if (cid.startsWith('Qm')) {
    // CIDv0 - can convert to CIDv1 if needed
    return cid;
  } else if (cid.startsWith('b') || cid.startsWith('f') || cid.startsWith('z')) {
    // CIDv1
    return cid;
  } else {
    throw new Error('Invalid CID format');
  }
};

3. Memoritza els mapatges de CID#

Si generes CIDs freqüentment, considera la memòria cau:

const cidCache = new Map();

const getCachedCID = (content) => {
  const contentHash = btoa(content);
  
  if (cidCache.has(contentHash)) {
    return cidCache.get(contentHash);
  }
  
  // Upload and cache result
  return uploadFile(content).then(cid => {
    cidCache.set(contentHash, cid);
    return cid;
  });
};

4. Utilitza descripcions significatives#

En pujar contingut, inclou metadades descriptives:

const uploadWithMetadata = async (content, metadata) => {
  return fetch('https://api.ipfs.ninja/upload/new', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bws_1234567890abcdef1234567890abcdef12345678',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content: btoa(content),
      description: metadata.name || 'Uploaded file',
      metadata: {
        filename: metadata.filename,
        contentType: metadata.contentType,
        uploadedAt: new Date().toISOString(),
        version: metadata.version || '1.0'
      }
    })
  });
};

Casos d’ús comuns de CID#

1. Desplegament de llocs web estàtics#

Desplega llocs web sencers a IPFS i referencia-los per CID:

// Upload website directory structure
const deployWebsite = async (files) => {
  const uploads = await Promise.all(
    files.map(file => uploadFile(file.content, file.path))
  );
  
  // Root CID references entire site
  const rootCID = uploads.find(u => u.path === 'index.html').cid;
  console.log(`Website deployed: https://ipfs.ninja/ipfs/${rootCID}`);
  
  return rootCID;
};

Per saber més sobre el desplegament de llocs web, mira la nostra guia sobre com pujar fitxers a IPFS.

2. Emmagatzematge de metadades NFT#

Emmagatzema metadades NFT de manera immutable utilitzant CIDs:

const nftMetadata = {
  name: "My Awesome NFT",
  description: "A unique digital collectible",
  image: "ipfs://bafkreibc5sgo2plmjkq2tzmhrn54bk3crhnqekiy7u66fqvqm37pu2e5gw",
  attributes: [
    { trait_type: "Color", value: "Blue" },
    { trait_type: "Rarity", value: "Epic" }
  ]
};

const metadataCID = await uploadFile(
  JSON.stringify(nftMetadata, null, 2), 
  'metadata.json'
);

// Use in smart contract
console.log(`Token URI: ipfs://${metadataCID}`);

3. Distribució de contingut#

Utilitza CIDs per a la lliurament distribuït de contingut:

// Upload once, access everywhere
const distributeContent = async (content) => {
  const cid = await uploadFile(content, 'content.txt');
  
  // Content available via multiple gateways
  const gateways = [
    `https://ipfs.ninja/ipfs/${cid}`,
    `https://ipfs.io/ipfs/${cid}`,
    `https://cloudflare-ipfs.com/ipfs/${cid}`
  ];
  
  return { cid, gateways };
};

Entenent el pinning d’IPFS amb CIDs#

Els CIDs són temporals per defecte — han de ser «fixats» per romandre disponibles. Aprèn més sobre aquest concepte crucial a la nostra guia completa sobre què és el pinning d’IPFS.

En triar un servei de pinning d’IPFS, considera llegir la nostra comparació IPFS Ninja vs Pinata o explora el nostre recull dels millors serveis de pinning d’IPFS disponibles avui.

Crea el teu primer CID en 30 segons#

Preparat per generar el teu primer CID? Aquí tens un exemple ràpid utilitzant l’API d’IPFS Ninja:

# Using curl (replace with your actual API key)
curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "SGVsbG8sIElQRlMgV29ybGQh",
    "description": "My first IPFS upload"
  }'
// Using JavaScript
const createFirstCID = async () => {
  const response = await fetch('https://api.ipfs.ninja/upload/new', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bws_YOUR_API_KEY_HERE',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content: btoa('Hello, IPFS World!'), // Base64: "SGVsbG8sIElQRlMgV29ybGQh"
      description: 'My first IPFS upload'
    })
  });
  
  const result = await response.json();
  console.log('🎉 Your first CID:', result.cid);
  console.log('🌐 Access it at:', result.uris.url);
  
  return result;
};

createFirstCID();

Això retornarà alguna cosa com:

{
  "cid": "bafkreif2pall7dybz7vecqka3zo24irdwabf7rbiiweuhau7a2hjlqvfjw",
  "sizeMB": 0.000017,
  "uris": {
    "ipfs": "ipfs://bafkreif2pall7dybz7vecqka3zo24irdwabf7rbiiweuhau7a2hjlqvfjw",
    "url": "https://ipfs.ninja/ipfs/bafkreif2pall7dybz7vecqka3zo24irdwabf7rbiiweuhau7a2hjlqvfjw"
  }
}

Per a exemples d’API més detallats, mira el nostre tutorial d’API d’upload IPFS.

Conclusió#

Els CIDs són el fonament del sistema d’adreçament de contingut d’IPFS, proporcionant identificació de contingut immutable, verificable i descentralitzada. Entendre com funcionen — des dels detalls tècnics de CIDv0 vs CIDv1 fins als patrons pràctics d’implementació — és essencial per construir aplicacions descentralitzades robustes.

Punts clau:

  • Els CIDs identifiquen el contingut de manera única, no ubicacions
  • CIDv0 proporciona compatibilitat màxima, CIDv1 ofereix flexibilitat
  • L’adreçament de contingut permet la verificació i la deduplicació
  • La gestió adequada de CID és crucial per a aplicacions de producció

Tant si estàs emmagatzemant metadades NFT, desplegant llocs web descentralitzats, o construint sistemes de distribució de contingut, els CIDs proporcionen la base fiable que necessites per a aplicacions realment descentralitzades.

Preparat per començar a fer pinning? Crea un compte gratuït — 50 fitxers, 1 GB d’emmagatzematge, 2 GB d’ample de banda/mes. Sense targeta de crèdit.

Nacho Coll

Sobre l'autor

Founder & Engineer at IPFS.NINJA

Nacho founded IPFS.NINJA to make content-addressed storage feel as simple as an S3 PUT — a single API call, a permanent CID, no wallets or peer discovery to reason about. Writes about IPFS internals, decentralized storage patterns, and the pinning-service landscape from the operator side of the wire.

Tornar al Blog

Articles Relacionats

Rendiment IPFS: Accelera la Recuperació amb Gateways
Guides

Rendiment IPFS: Accelera la Recuperació amb Gateways

29 de juny del 20267min de lectura
Tokens de Pujada IPFS: Pujades Segures del Client
Guides

Tokens de Pujada IPFS: Pujades Segures del Client

6 d’abr. del 202613min de lectura
Emmagatzematge de Metadades NFT: Guia IPFS per a Creadors
Guides

Emmagatzematge de Metadades NFT: Guia IPFS per a Creadors

30 de març del 202610min de lectura