Come importare prodotti in Magento 2 in 2026: La guida operativa per 2.4.8 - IT

Adobe ha spedito Magento 2.4.8 ad aprile 8, 2025, e il modo in cui i grandi cataloghi si spostano attraverso la piattaforma è stato finalmente aggiornato 2026. Gli endpoint di importazione REST nativi (/V1/importa/csv e /V1/import/json) ora accetta payload con codifica base64 e compressione gzip. Questo uccide il vecchio “dividi il tuo CSV in 500 righe e pregare” routine. L'importatore CSV amministrativo a cui si affida ancora la maggior parte dei negozi? Stesso strumento, soprattutto. Ma i modi in cui si rompe sono cambiati, e così anche le soluzioni. Questa guida copre entrambi i percorsi, e gli errori che mangiano un fine settimana quando ti mancano.

Risposta rapida: Per i cataloghi sotto 5,000 SKU, utilizzare l'importatore CSV amministrativo in Sistema > Trasferimento dati > Importare. Per qualsiasi cosa più grande o automatizzata, colpisci il Endpoint REST /V1/import/csv aggiunto 2.4.8. Mantieni i file UTF-8 senza BOM, rilasciare le immagini in var/import/immagini, e corri sempre “Controlla i dati” prima di impegnarsi.

Ultima revisione: aprile 2026. Endpoint, numeri di versione, e comportamenti di importazione verificati rispetto ad Adobe Commerce 2.4.8 note di rilascio e la documentazione di Experience League.

Prima di iniziare: Cosa è cambiato in 2.4.8

Se hai importato prodotti su Magento 2.4.5 o prima, alcune impostazioni predefinite si sono allineate alla realtà. Nuovo 2.4.8 installa la spedizione con gli indicizzatori in Aggiornamento in base alla pianificazione modalità, quindi le importazioni di massa non bloccano più il frontend durante la reindicizzazione. Il rilascio è stato chiuso 497 bug fondamentali (diversi sull'importatore stesso) e aggiunto gli endpoint di importazione REST che aggirano il limite massimo di caricamento amministrativo di 2 MB.

Ecco cosa ti serve prima di contattare l'importatore:

• Magento 2.4.8 o più tardi. Corsa 2.4.5 o più vecchio? Aggiorna prima. L'importatore più vecchio funziona ancora, ma le correzioni dei bug non vengono sottoposte a backport.
• PHP 8.3 minimo, 8.4 consigliato. 2.4.8 viene fornito con PHP nativo 8.4 supporto. Negozi su PHP 8.1 importerà, ma la gestione degli errori è più rumorosa.
• MySQL 8.0 o MariaDB 10.6/11.4. 2.4.9-la beta1 elimina MySQL 8.0 e MariaDB 10.6, quindi se ti stai preparando da zero, andare 11.4.
• Una directory scrivibile var/import/images. permessi: 775 per le directory, 664 per i file, di proprietà del tuo utente web.
• Limiti PHP sufficienti. Per i cataloghi finiti 10,000 SKU, limite_memoria 2G e tempo_max_esecuzione 1800 nel file php.ini. Valori più bassi interromperanno silenziosamente le importazioni durante il processo.

Un rapido avvertimento: Adobe Commerce (il livello a pagamento) e Magento Open Source condividono il codice importatore. I clienti cloud non hanno bisogno di toccare php.ini perché lo stack è già ottimizzato, ma le regole e i comportamenti CSV riportati di seguito si applicano in modo identico.

Cosa puoi effettivamente importare

Magento 2 ha sei tipi di prodotto, e le regole CSV cambiano a seconda di quale stai spostando. La versione breve:

• Prodotti semplici. Uno SKU, una variazione. Il modello utilizzato da ogni tutorial. Importali prima se stai imparando.
• Prodotti configurabili. Uno SKU genitore con semplici figli allegati tramite varianti_configurabili. Taglia e colore delle magliette sono l'esempio da manuale. I figli devono esistere prima della riga di importazione padre, oppure il collegamento fallisce.
• Prodotti virtuali. Servizi, abbonamenti, copertura della garanzia. Nessun calcolo della spedizione, non è necessaria alcuna colonna di peso.
• Prodotti raggruppati. Un wrapper che mostra diversi semplici su una pagina (pensare “set di coltelli da cucina, acquistare singolarmente”). Usi associate_skus nel CSV.
• Prodotti in bundle. Crea combinazioni personalizzate in cui il cliente sceglie le opzioni. Il formato è complicato e utilizza bundle_values con campi separati da tubi.
• Prodotti scaricabili. File, licenze software, ebook. Esigenze link_scaricabili configurato.

L'ordine di importazione è importante. Prima i semplici, quindi configurabili che fanno riferimento ad essi, quindi raggruppati e raggruppati per ultimi. L'importazione di un configurabile i cui SKU secondari non esistono ancora è l'errore autoinflitto più comune, e il validatore non sempre lo rileverà prima dell'esecuzione dell'importazione.

Importazione CSV: La procedura dettagliata dell'amministratore

L'importatore CSV di amministrazione gestisce i cataloghi fino a circa 5,000 SKU senza reclamo. Vale la pena saperlo anche se prevedi di passare all'API in un secondo momento, perché le regole della colonna che seguono si applicano a entrambi i percorsi.

Passo 1: Esporta un file di esempio (Non saltare questo)

Vai a Sistema > Trasferimento dati > Importare. Impostato Tipo di entità per Prodotti, quindi fare clic Scarica il file di esempio. L'esempio corrisponde esattamente alla tua installazione di Magento, inclusi eventuali attributi personalizzati aggiunti dal tuo negozio. L'utilizzo di un modello CSV generico da un post del blog è l'inizio degli errori di mancata corrispondenza delle colonne.

Salvare il campione, aprilo in Notepad++ o VS Code. Non utilizzare Microsoft Excel. Excel aggiunge un contrassegno dell'ordine dei byte ai file UTF-8, e l'importatore rifiuta i file con prefisso BOM senza un chiaro messaggio di errore. Se Excel è la tua unica opzione, esportare come “CSV UTF-8” ed eseguire il file tramite un programma di rimozione BOM, o passa a Fogli Google (File > Scarica > CSV, che salva UTF-8 pulito).

Passo 2: Compila le righe del prodotto

Colonne obbligatorie per un prodotto semplice: sku, store_view_code, codice_set_attributo, tipo_prodotto, categorie, prodotti_siti web, nome, descrizione, prezzo, quantità, peso, prodotto_online, nome_classe_tasse, visibilità.

Conserva le descrizioni sotto ~255 caratteri per riga se utilizzi l'importatore amministrativo. Le descrizioni HTML più lunghe funzionano, ma aumentano rapidamente le dimensioni del file e trascinano il limite predefinito di 2 MB più vicino. Le categorie utilizzano le barre per costruire la gerarchia: Categoria predefinita/Abbigliamento/T-shirt. Il separatore è una barra, non una barra rovesciata. Un sollievo: Magento crea automaticamente percorsi di categorie che non esistono ancora, quindi non è necessario precostruire ogni categoria prima dell'importazione.

Per configurabili, il varianti_configurabili la colonna contiene una stringa delimitata da pipe come:
sku=CAMICIA-ROSSO-S,taglia=S,colore=Rosso|sku=CAMICIA-ROSSO-M,taglia=M,colore=Rosso

Poco pratico, sì. Risparmiati fatica esportando prima un configurabile costruito a mano, quindi utilizzando quella riga come modello per quella successiva 5,000.

Passo 3: Configura il comportamento di importazione

Cosa succede quando uno SKU nel tuo CSV esiste già nel catalogo? Decidono tre opzioni di comportamento, e scegliere quello sbagliato può cancellare i dati:

• Aggiungi/Aggiorna. La scelta predefinita e sicura. Aggiunge nuovi SKU, aggiorna quelli corrispondenti, lascia da parte i prodotti non elencati.
• Sostituire. Elimina prima gli SKU corrispondenti, quindi li ricrea dal CSV. Cancella gli URL, recensioni, e la cronologia dei movimenti delle scorte di tali prodotti. Utilizzare raramente.
• Elimina entità. Rimuove gli SKU corrispondenti dal catalogo. Irreversibile senza ripristino del database.

Anche impostato Separatore di campo alla virgola, Separatore di valori multipli alla virgola, e controlla Conteggio errori consentiti. L'impostazione predefinita è 10. Portalo a un numero più alto se prevedi che alcune righe falliscano e desideri che l'importatore continui anziché interrompere.

Passo 4: Convalida prima dell'importazione

Carica il tuo CSV, clic Controlla i dati, e aspetta. Viene eseguita la stessa convalida eseguita dall'importazione reale, ma senza scrivere nel database. L'output elenca ogni errore di riga in base al numero con la colonna specifica che non è riuscita. Correggi il CSV, ricaricare, ricontrollare. Risciacquare fino al verde.

Se la convalida dice “Il file è valido” ma compaiono alcuni avvisi, leggili comunque. Negli avvisi spesso mancano percorsi di categoria o visualizzazioni di negozi che Magento salterà silenziosamente, creazione di prodotti con alberi di categorie incompleti.

Passo 5: Esegui l'importazione

Clic Importare. La barra di avanzamento è onesta per i file di piccole dimensioni e ottimistica per quelli di grandi dimensioni. Non chiudere la scheda del browser. Non aggiornare. L'importatore esegue un unico lungo processo PHP, e su hosting più lento, la chiusura della scheda durante la scrittura rende orfano il processo e lascia dietro di sé dati parziali. Orologio var/log/import.log su SSH se vuoi progressi in tempo reale, o controlla Sistema > Importa cronologia una volta terminato.

Immagini e media

Le immagini confondono più importazioni di qualsiasi altro campo. La regola è semplice dopo averla vista una volta.

FTP o SFTP in cui inserire i file di immagine <Radice Magento>/var/import/immagini. Sono consentite le sottocartelle: var/import/images/2026-spring lavori. Nel CSV, fare riferimento a ciascuna immagine tramite il suo percorso relativo a var/import/immagini:

• immagine_base colonna: immagine principale del prodotto (mostrato nella pagina del prodotto)
• small_image colonna: miniatura per le pagine di categoria
• miniatura_immagine colonna: carrello e miniature degli ordini
• immagini_addizionali colonna: immagini della galleria, separati da virgole

Potrebbe apparire una riga che importa un prodotto con quattro scatti della galleria: /2026-primavera/tshirt-red-main.jpg in immagine_base, poi /2026-primavera/tshirt-red-back.jpg,/2026-primavera/tshirt-red-detail.jpg,/2026-primavera/tshirt-red-fabric.jpg in immagini_addizionali.

Guarda la denominazione dei file. Dolcetti Magento Camicia.jpg e camicia.jpg come file diversi su host Linux, e l'importatore non corregge automaticamente il caso. Se puoi, comprimi su WebP prima del caricamento; gli scatti eroici a 300-400KB JPEG riempiranno i tuoi Core Web Vitals nel momento in cui arriverà il traffico reale. I nostri Manuale di velocità Magento copre la conversione WebP e AVIF per i cataloghi esistenti.

Importazione API REST: Il 2.4.8 Percorso per cataloghi di grandi dimensioni

L'importatore amministrativo termina rapidamente. Una volta che hai passato 10,000 SKU o hai bisogno di sincronizzazioni automatizzate da un ERP, gli endpoint REST forniti da Adobe 2.4.8 sono lo strumento giusto. Due endpoint contano:

• POST /riposo/<codice_negozio>/V1/importa/csv per i payload CSV
• POST /riposo/<codice_negozio>/V1/import/json per i payload JSON

Entrambi accettano una stringa con codifica base64 nel corpo della richiesta. Per CSV, la regola è: Codifica UTF-8 il tuo file, gzip-comprimerlo (opzionale ma intelligente per qualsiasi cosa superiore a 1 MB), quindi base64 il risultato. La risposta restituisce un conteggio delle entità importate. Bulk asincrono tramite /V1/sfuso/ funziona anche se vuoi "spara e dimentica"..

Il flusso, al fine:

• Autenticarsi con un token amministratore (POSTARE a /V1/integrazione/admin/token)
• Comprimi il file product.csv, codificarlo in base64, inserirlo in un payload JSON con fonte, entità: “catalogo_prodotto”, e comportamento: “aggiungere”
• POST sull'endpoint di importazione con il token nell'intestazione Authorization
• Sondaggio /V1/sfuso/{bulkUuid}/stato se sei andato in asincrono

Adobe’s developer docs carry the exact payload shape and update per release, so pull from there rather than copying old StackOverflow threads. Il 2.4.8 payoff: the async path doesn’t hold a PHP request open for up to 30 minutes the way the admin importer does. Your 50,000-row load runs in the background, and the storefront stays responsive to actual shoppers.

Errori di importazione comuni e cosa li risolve effettivamente

These are the failures that burn the most time. Each one has a specific root cause that isn’t always obvious from the error text.

“Allowed memory size of X bytes exhausted”

PHP ran out of memory mid-import. Raise memory_limit in php.ini to 2G, restart PHP-FPM, retry. If you can’t touch php.ini (hosting condiviso), split the CSV into files of 1,000-5,000 rows each and import sequentially. Third-party extensions like Firebear and Amasty add an “Import without Memory Limit” toggle, ma questa è una funzionalità di estensione, non nativo di Magento.

“Tempo massimo di esecuzione di 30 secondi superati”

Il tuo PHP tempo_max_esecuzione è troppo basso. Vai a 1800 secondi. Su Nginx, dovrai anche rilanciare fastcgi_read_timeout abbinare, altrimenti Nginx uccide l'upstream prima che PHP finisca.

“Sequenza di colonne errata” o “L'intestazione contiene colonne non valide”

Contrassegno dell'ordine dei byte. Il tuo CSV è stato salvato da Excel, che antepone una distinta base ai file UTF-8 che l'importatore legge come una prima colonna confusa. Riesporta da Fogli Google o salva nuovamente tramite Notepad++ come UTF-8 senza distinta materiali. Se controlli solo una cosa prima di premere import, controlla questo.

“Insieme di attributi non valido” o “Valore dell'attributo non valido per X”

Il tuo CSV fa riferimento a un set di attributi o a un valore a discesa che non esiste in questa installazione di Magento. Controllo Negozi > Attributi. I valori a discesa fanno distinzione tra maiuscole e minuscole e sensibili agli spazi bianchi. “Rosso ” con uno spazio finale non lo è “Rosso”.

Importare “completa” ma i prodotti non vengono visualizzati sul frontend

Reindicizzazione non è stata eseguita, oppure la cache è obsoleta. Accedi ed esegui SSH indicizzatore bin/magento:reindicizzare seguito da cache bin/magento:a filo. Su 2.4.8 con l'aggiornamento tramite indicizzatori pianificati questo è più raro, ma accade ancora con l'URL del prodotto e gli indicizzatori azionari.

“La chiave URL per il negozio specificato esiste già”

Stai importando un prodotto di cui chiave_url si scontra con uno esistente. Modifica la chiave URL nel tuo CSV o imposta il comportamento su “Aggiungi/Aggiorna” piuttosto che un fresco “Aggiungi dati complessi” correre.

Requisiti di hosting per grandi importazioni

L'hosting condiviso uccide più importazioni Magento rispetto ai CSV scadenti. Se stai eseguendo una produzione 2.4.8 memorizzare, il piano onesto è 4 GB di RAM e 2-4 CPU virtuali; veri e propri cataloghi (10k+ SKU, frequenti reimportazioni) Bisogno 8-16 GB. Il disco dovrebbe essere un SSD NVMe, unità non rotanti o vecchi SSD SATA, perché le operazioni di reindicizzazione e ridimensionamento delle immagini martellano I/O casuali.

Cose specifiche che un host pronto per Magento dovrebbe lasciarti fare:

• Modifica php.ini (o equivalente per dominio) per aumentare memory_limit e tempo di esecuzione
• Installa ed esegui cron (L’importazione di massa asincrona di Magento utilizza la coda dei consumatori)
• Accesso SSH per bin/magento Comandi CLI
• Abbastanza spazio sul disco var/import/immagini può contenere il tuo lotto più grande due volte (Copie Magento, non si muove)

Se il tuo attuale host non può consegnarli, l’importatore non è il tuo vero problema. I nostri Riepilogo dell'hosting Magento VPS analizza quali fornitori spediscono uno stack pronto per 2.4.8 senza supplementi, e il strumento di ricerca dell'hosting filtri per versione PHP, RAM, e pannello di controllo se desideri confrontare i piani fianco a fianco. Per i commercianti che utilizzano WooCommerce insieme a Magento (succede più di quanto pensi), il Guida all'hosting e-commerce WordPress copre lo stack crossover.

Domande frequenti

Qual è la dimensione massima del file CSV che posso importare in Magento 2.4.8?

L'importatore amministrativo limita i caricamenti a 2MB per impostazione predefinita, controllato da PHP upload_max_dimensionefile e post_max_size. Aumenta entrambi a 64M in php.ini per file più grandi. Per qualsiasi cosa oltre i 50 MB compressi, passare al RESTO /V1/importa/csv punto finale, che gestisce i payload gzip e non crea colli di bottiglia nel caricamento del browser.

Posso importare prodotti in Magento 2 senza utilizzare CSV?

sì. L'API REST di Magento 2.4.8 accetta sia CSV che JSON tramite /V1/import/json. Estensioni di terze parti (Orso di fuoco, Amasty, Magmi per installazioni precedenti) supportare l'XML, Sincronizzazione di Fogli Google, e connettori ERP diretti. L'amministratore nativo richiede ancora CSV, quindi scegli il tuo percorso in base alle esigenze di automazione.

Quanto tempo impiega un'importazione di 10.000 prodotti?

Su un sintonizzato 2.4.8 pila (8 GB di RAM, NVMe, PHP 8.4, MariaDB 11.4), aspettarsi 15-25 minuti per un'importazione di 10.000 righe con immagini. L'hosting condiviso spinge a questo 60+ minuti se viene completato. Il percorso in blocco REST asincrono viene eseguito in background, in questo modo le pagine rivolte agli acquirenti rimangono reattive durante l'importazione.

Perché la mia importazione ha esito positivo ma mostra prezzi o scorte errati?

Due cause solite. Primo, il tuo CSV ha spazi bianchi finali o formattazione virgola decimale europea (1,99 invece di 1.99) nella colonna del prezzo; Magento li analizza come non validi e mantiene il vecchio valore. Secondo, inventario multi-fonte (MSI) in 2.4.8 memorizza la quantità per fonte, non per prodotto a livello globale, quindi ti serve il codice_sorgente o l'importazione aggiorna solo l'origine predefinita.

Devo disabilitare il catalogo flat Magento prima dell'importazione?

Il catalogo flat è stato deprecato a partire dal 2.3 e rimosso dai flussi di lavoro predefiniti da 2.4.5. Se il tuo negozio in qualche modo lo ha ancora abilitato, disabilitalo sotto Negozi > Configurazione > Catalogare > Storefront prima delle grandi importazioni. È sempre stata una responsabilità di prestazione e 2.4.8 lo rende esplicito nell'amministratore.

Posso automatizzare le importazioni di prodotti da un ERP o PIM?

Questo è esattamente ciò che 2.4.8 Gli endpoint REST servono. Strumenti come Akeneo, PimCore, e Salsify hanno Magento nativo 2 connettori. Per costruzioni personalizzate, cron uno script che estrae il tuo feed ERP, si trasforma in CSV, gzips, e POST a /V1/importa/csv. Pianifica le ore non di punta se l'importazione è pesante.

Note finali

Due regole decidono se la tua prossima importazione funziona. Uno: salva il CSV come UTF-8 senza BOM. Sempre. Due: aumentare PHP memory_limit e tempo_max_esecuzione prima che inizi, non dopo il primo incidente. Tutto il resto è dettaglio.

Per quanto riguarda il percorso, la chiamata è semplice. Sotto 5,000 SKU e importazioni in esecuzione occasionalmente? Utilizza lo strumento CSV di amministrazione. Passato 10,000 SKU o sincronizzazione notturna da un ERP? Usa il RESTO /V1/importa/csv endpoint aggiunto 2.4.8 e smetti di fare da babysitter al processo. Eseguire il backup del database prima di eseguire qualsiasi operazione di sostituzione o eliminazione. Non chiudere mai la scheda del browser durante l'importazione. E se la pila sottostante non regge, nessuna tattica dell’importatore lo salva. Correggi prima l'host.

Per letture correlate: il Raccolta dei temi Magento copre le prestazioni del frontend dopo il caricamento del catalogo, lo speed playbook collegato sopra gestisce lo stack di memorizzazione nella cache, e le guide di hosting spiegano su cosa eseguire il tutto. Le noiose scelte infrastrutturali si accumulano più velocemente di qualsiasi singolo indicatore di funzionalità.