n8nでCSVを読み取り・書き出すときの確認点

この記事は、CSVファイルを受け取り、n8n内で加工して別のCSVとして渡す場合の説明です。公開仕様と公式ソースに基づく設定例であり、掲載したデータは実行結果と区別した説明用の仮例として読んでください。

CSVファイルとJSON行を変換する向きを決める

読み取りにはExtract From FileのExtract From CSV、書き出しにはConvert to FileのConvert to CSVを使います。まず区別したいのは、ファイルの個数と、ファイルの中にあるデータの件数です。

ここでいうitemは、ノード間を流れるデータの単位を指します。1itemの中に配列がある状態と、独立した3itemsは同じではありません。配列を含むだけで3行のCSVになると考えず、ファイル化する直前のJSONを見てください。

ファイル本体はbinary側にあり、その中のフィールド名で受け渡します。たとえば入力がbinary.sourceCsvなら、読み取りノードへ指定する名前はsourceCsvで、ファイル名のinput.csvとは別の値です。

ヘッダー・区切り・文字・空欄の約束をそろえる

CSVは文字で表を表す形式なので、拡張子が.csvでも読み方が一つに決まるわけではありません。入力元と受け取り先の約束をそろえることが、設定選びの出発点です。

列名と区切りを決め、引用符の中の改行を残す

先頭行が列名ならHeader Rowを有効にし、Delimiterには実際の区切り文字を指定します。複数列が一つの値に見える場合は、セミコロン区切りのファイルをカンマで読んでいるなど、区切りの不一致が一因です。

列名には空欄・重複・意図しない前後の空白を残さないようにしましょう。たとえばcodeとcodeの後ろに空白が付いたキーは、見た目が似ていても後続の参照先が異なるためです。

引用符で囲まれた値の中には、改行を含めることも可能です。そのため、テキストの物理的な行数と、データ1件分のrecord数は一致しません。単純にカンマや改行で文字列を分割せず、CSVとして解析してください。

この引用の基本はRFC 4180でも説明されています。ただし同文書はInformationalの資料で、セミコロンやタブなどを使う相手の独自仕様まで統一するものではありません。

文字コードとBOMを別々に確かめる

Encodingは、実ファイルの文字コードに合わせます。以下の作例はUTF-8を前提にしますが、Shift_JISやCP932のファイルをUTF-8と指定するだけで変換できるわけではありません。

2026年10月31日に確認した公式ソースの読み取り選択肢にはCP932が含まれていないため、「EncodingでShift_JISを選ぶ」という固定手順にするのは不適切です。提供元にUTF-8で再出力してもらうか、許可された方法で別ファイルへ変換し、原本を残してください。

BOMは、文字コードの手掛かりとして先頭に付く情報です。読み取り側のExclude Byte Order Mark (BOM)は、存在するBOMを検出して除く設定であり、出力ファイルへBOMを追加する機能とは区別しましょう。

先頭のキーがidに見えるのに参照できないならBOMや空白を、日本語の「東京」そのものが崩れているなら文字コードを調べます。どちらも「文字化け」の一言で片付けると、直す設定を選びにくくなるためです。

先頭ゼロ・0・空文字・nullを別の値として考える

商品コードや郵便番号などの識別子は、計算する数値ではなく文字列として保つ方針にします。数量を数値に直す場合も、識別子と同じ変換をかけないでください。

Include Empty Cellsを無効にすると、空文字の項目がJSONから欠ける場合があります。有効なら空セルを空文字として含められますが、それだけで元のnull・空文字・存在しない列を完全に復元できるわけではありません。

また、0を「値がない」と扱う判定は避けましょう。厳密な往復が必要なら、欠損をどう表すかまで受け渡し仕様に含める必要があります。

読み取り直後にcodeが文字列の「00123」かを確かめ、後段で識別子へ数値変換をかけないようにしてください。元のCSVですでに「123」になっていた値は、文字列へ変えるだけでは「00123」に戻りません。ゼロが消えた最初の段階を、原本・読み取り直後・整形後・Excel表示の順で比較します。

Extract From FileでCSVを読み、行の中身を確かめる

まずは許可された小さなダミーファイルで、JSONへ変えた直後の内容を確かめるところから始めましょう。外部への書き込みはつながず、入力の約束と読み取り結果が合う段階までで止めてください。

1. ファイル本体とbinary名を確認する

   前のノードの出力で、CSV本体を持つフィールドを探します。作例ではbinary.sourceCsvを入力とし、ファイル名だけがJSONに入っている状態とは区別しましょう。

2. Extract From CSVを選ぶ

   Extract From FileでOperationをExtract From CSVへ設定します。Input Binary FieldにはsourceCsvを指定し、実データがdataなど別名ならその名前へ合わせてください。

3. CSVの約束をOptionsへ反映する

   作例はDelimiterがカンマ、EncodingがUTF-8、Header Rowが有効、Include Empty Cellsも有効という条件です。BOM付きの入力なら除外設定も照合し、開始位置・最大件数・エラー行のスキップを使うかどうかまで確認しましょう。

4. 件数とキーを見てから後続へ進む

   出力items数だけでなく、code・name・quantity・noteが期待どおりのキーか調べます。先頭と末尾のID、日本語、0、空欄のいずれかが違えば、書き出す前に入力ファイルと設定へ戻ってください。

ヘッダー付き3recordsなら、ヘッダーを列名として読むことで3itemsになるのが期待例です。Header Rowを無効にするとヘッダーもデータになり、公開ソースではjson.row配下へ入る構造となるため、同じ$json.code参照をそのまま使えません。

code,name,quantity,note00123,東京,0,"赤,青"00124,大阪,2,"1行目2行目"00125,福岡,1,

複数ファイルを一度に読む場合は、それぞれの元ファイルIDと出力行の対応も残しましょう。総数だけが合っていても、どのファイルから出た行か分からなければ、欠落の切り分けや再処理に困るためです。

CSVのエラー処理にはノード版による違いもあります。導入しているn8n版とノード版を記録し、ここで示した設定名が同じでも、出力とエラーの出方を実データで照合してください。

列を整え、Convert to FileでCSVへ書き出す

書き出す前に、渡す列と値を明確にします。JSONに入っている全項目をそのまま表にすると、内部メモや不要な情報まで出力へ混ざる可能性があるためです。

必要な列だけを同じ形にそろえる

作例なら、3itemsすべてにcode・name・quantity・noteを同じ意味で持たせます。列順の期待も決め、ネストしたオブジェクトや途中のitemだけにある余分なキーが残っていないか見てください。

公式の公開実装では、各itemのJSONを平坦化して表へ変換します。ネストが意図しない列へ展開されたり、後のitemで登場したキーが列を増やしたりする可能性があるので、ファイル化の直前で出力項目を絞ることが大切です。

1item内に配列があるなら、先に複数itemsへ展開する必要があるかを判断しましょう。AggregateとSplit Outを扱う関連記事では、配列をまとめる処理と、配列から行を増やす処理の違いを確認できます。複雑な独自変換だけが必要な場合にCodeを検討し、CSV変換のために毎回コードを書く必要はありません。

ファイル名と出力binary名を別々に指定する

出力binary名は後続が参照する項目名、ファイル名は保存物の名前です。

1. Convert to CSVを選ぶ

   整えた行データをConvert to Fileへ渡し、OperationでConvert to CSVを選んでください。作例の3itemsを受け取り、一つのCSVへまとめる流れを想定します。

2. binary名とCSVの仕様を決める

   Put Output File in FieldをexportCsv、File Nameをreport-test.csvとするのが作例です。Header Rowを有効にし、導入版で使えるDelimiterも受け取り先の仕様へ合わせてください。

3. 出力を確認して別名のテスト先へ渡す

   binary.exportCsvにファイルがあるか、ファイル名・MIME・ファイル数が想定どおりか調べます。次のアップロードノードにもexportCsvを指定し、保存先の権限を確認してから正本と別の場所へ渡しましょう。

現行の公開ソースでは、CSV操作は受け取った複数itemsから一つのbinaryファイルを返す構造です。出力のjsonは空で、元の行データをそのまま保持するとは限らないため、必要な照合用データは前段へ残してください。

同じノードにあるJSON操作の「All Items to One File」「Each Item to Separate File」は、CSV操作のモードではありません。3recordsだから3ファイルになると考えず、分割が要る場合は別途その単位を設計しましょう。

CSVのEncodingやBOMも、Text・JSON操作にある設定を借りて案内しないことが重要です。受け取り先が特定の文字コードやBOMを要求するなら、利用中の版で可能な方法を確認し、生成ファイルの実バイトと読み戻し結果で照合してください。

読み戻しで値とrecord数を照合する

作ったCSVをExtract From Fileで再び読み、出力前のJSONと比べます。変更する予定だった値と、保持したい値を分けて記録するのが確認の軸です。

3件の仮例で、IDと値の対応を見る

以下は往復確認用の設計例であり、実行済みの結果表ではありません。noteの「1行目（改行）2行目」は、一つのフィールド内に改行が入るケースを示します。

件数が3で合っていても、00123が重複して00124が抜けていれば一致とはいえません。IDの集合に加えて、重複の有無とIDごとの値を照合しましょう。

• 入力ファイル数、出力ファイル数、データrecords数を別々に数えたか
• 期待したIDがそろい、意図しない重複がないか
• 列名と列順、必須列、許可した空欄が仕様どおりか
• 00123、日本語、quantityの0、カンマと改行が保持されたか
• 数値化や列名変更など、意図した差だけを説明できるか

引用符の付け方や改行コードなどが変わっても、論理的な値が同じなら目的を満たせる場合があります。バイト単位の完全一致が必要な契約でなければ、まず値の意味と受け取り側の条件を完了基準にしてください。

空ファイル、ヘッダーのみ、複数ファイル、引用符の不整合は、通常の3件とは別ケースです。対象データで起こり得るものを追加し、異常時に後続の書き込みを止められるかまで確認しましょう。

Excelの自動変換と、数式としての解釈を切り分ける

n8nで読み戻したcodeが00123のままなのに、Excelで123に見えるなら、開く側の自動型変換を調べます。ダブルクリックだけで開かず、Text/CSVからのインポートなどで識別子の列を文字列に指定してください。

MicrosoftはUTF-8のCSVを通常どおり開く条件としてBOMを案内しています。ただしBOMは先頭ゼロや長いIDの型を保つ保証ではありません。自動変換を制御する設定の有無もExcelの版で異なるため、文字コードの認識と列型の指定は別に確かめましょう。

さらに、外部から受け取った未信頼の文字列がある場合は、数式として解釈される危険も別に扱います。CSVの引用符はカンマや改行から値を守る構文上の処理であり、それだけで表計算ソフトの式評価を止めることはできません。

一律に先頭へ文字を足す方法は、元データそのものも変えます。機械連携用の正規データと、人が表計算で開く配布物を分け、受け取り先に合うテキストの扱いと危険値の確認方法を決めましょう。

全アプリに共通する万能な無害化は前提にできません。正規データを壊さず、表示用に何を変えたかを残す方針が必要です。

読めない・一列になる・件数が減る場合の確認順

不調が起きたら、変化した最初の段階へ戻ります。大きなフローを一度に直すより、原本と設定を残した別フローで、最小のダミーrecordに絞って調べましょう。

容量が大きい場合は、ファイルの保存場所だけでなく、CSVをJSONの多数itemsへ展開する負荷も考えます。binaryの保存方式を変えれば全て解消するとはいえないので、小さい入力で成功するか、どの段階で負荷が増えるかを分けてください。

戻す際は、保持した原本と変更前のフローへ戻し、テスト用の別名ファイルや不要な実行履歴を保存方針に沿って整理しましょう。外部へ送ったCSVは、フローを戻すだけでは回収できません。正本への試し上書きや、全エラーを無視したままの配布は避けましょう。

まとめ｜CSVの列と値を読み戻して確かめる

n8nのCSV入出力は、Extract From Fileで読み、列と型をそろえ、Convert to Fileで書く流れが基本です。binary名・ヘッダー・区切り・文字コード・BOM・空欄を受け渡しの約束に合わせ、records数とファイル数を区別しましょう。

最初の一歩は、3件程度のダミーデータで確認表を作ることです。00123、日本語、0、空欄、カンマと改行を含む値を用意し、生成CSVを読み戻してIDごとの値まで照合してください。

CSVが出力できた瞬間よりも、受け手が必要な値を同じ意味で受け取れることを完了基準にするのが、手戻りを減らす判断になります。Excelの表示や未信頼文字列の式解釈まで、確認範囲に含めておきたいところです。

目的がCSVファイルではなくGoogle Sheetsの行の取得・更新なら、Sheets連携の記事へ進みましょう。認証、更新対象の行キー、書き込み後の読み戻しを確認することで、ファイル変換とは異なる更新の要点を整理できます。