JSONで改行がそのまま書けない理由｜\nエスケープの仕組みと実務での解決策

\n を書いたつもりが、実際には \\n と書いてしまっていたケースもよくあります。

• \n → 改行として解釈される（正しい）
• \\n → バックスラッシュ＋n という2文字の文字列として解釈される（意図と違う）

逆に、テキストをそのままJSONに流し込んだとき、文章中に \ が含まれていると \\ にエスケープされていないせいでエラーになることもあります。

私が実際にこれで詰まったのは、Claudeが生成したMarkdown本文をそのままJSONのフィールドに埋め込もうとしたときです。本文中にコードブロックの ` や \ 記号が含まれていて、JSONとして不正な文字列になっていました。エラーメッセージを見ても最初はどこが問題かわからず、30分ほど原因を探しました。

VSCodeで確認・修正する方法

JSONファイルに問題がある場合、VSCodeで素早く確認・修正できます。どうやって確認すればいいか、迷ったことはありませんか？

方法① 検索・置換で\nを確認する

VSCodeの検索（Ctrl+H）で、正規表現モードをオンにすると改行文字そのものを検索できます。

検索ボックスに \n と入力して正規表現モード（.* アイコン）をオンにすると、ファイル内の実際の改行位置がハイライトされます。これで「JSONの文字列値の中に生の改行が入っていないか」を確認できます。

もし文字列内に改行が見つかったら、置換ボックスに \\n と入力して置換します。これで生の改行文字が \n というエスケープ表記に変換されます。

検索（正規表現）：\n
置換：\\n

ただしこれはファイル全体の改行を置換するため、JSONの構造的な改行（各キーの間の改行）も置換してしまいます。文字列値の内部だけを対象にしたい場合は、より絞り込んだ正規表現が必要です。

方法② JSON整形・バリデーションで確認する

VSCodeのコマンドパレット（Ctrl+Shift+P）から「Format Document」を実行すると、JSONの構文エラーがある場合に赤いエラー表示が出ます。また、VSCodeのステータスバー右下に「JSON」と表示されているときは、JSON構文のバリデーションが自動で走っています。エラーがあると波線が表示されるので、その箇所を確認します。

実務での根本解決：JSONに本文を入れない

エスケープの方法を覚えることは大切ですが、そもそもJSONに長いテキスト本文を入れない設計にするのが、根本的な解決策です。

body.mdに分離する

私がbizinets.lifeの記事管理で実際に採用している方法です。記事のメタデータ（タイトル・slug・seoDescriptionなど）はJSONに入れますが、本文はMarkdownファイル（body.md）として別ファイルに分離します。

articles/
  my-article/
    article.json   ← メタデータのみ
    body.md        ← 本文（改行・記号を自由に書ける）
    eyecatch.svg

article.json の中身はこうなります。

{
  "title": "記事タイトル",
  "slug": "my-article",
  "seoDescription": "120文字以内の説明文"
}

本文は body.md に直接Markdownで書きます。改行も記号も、エスケープを気にせず自由に書けます。

なぜこの設計が有効か

判断基準として整理するとこうです。

• JSONフィールドの値が1行・短いテキストか → JSONに書いてよい
• JSONフィールドの値が複数行・Markdownを含むか → 別ファイルに分離する
• edit_file でJSONを直接修正する予定があるか → 本文は分離した方がエラーが起きにくい

長い本文をJSONに入れると、エスケープミス・edit_file の exact matchエラー・ファイルが重くなることによるパース遅延など、副次的な問題が連鎖しやすくなります。「JSONはメタデータ専用、本文は別ファイル」という設計にするだけで、これらの問題をまとめて回避できます。

よくある質問

Q: JSONではなくJavaScriptで書けば改行を直接入れられますか？

JavaScriptのオブジェクトリテラル（const obj = { key: "value" }）では、ES2015以降のテンプレートリテラル（バッククォートで囲む記法）を使えば改行を直接入れられます。ただしJSONとJavaScriptオブジェクトは別物です。JSON.parse() や外部ファイルとしての .json は厳密なJSON仕様に従うため、改行の直接記述はできません。

Q: AIが生成したテキストをJSONに入れるとよくエラーになります。なぜですか？

AIが生成するテキストには改行・ダブルクォート・バックスラッシュが頻繁に含まれます。これらをJSONの文字列値としてそのまま埋め込もうとすると、エスケープが必要な文字が必ず混入します。AI生成テキストをJSONに入れる場合は、プログラム側で JSON.stringify() を通すか、テキスト自体を別ファイルに分離することをおすすめします。

まとめ

仕様のルールとしては「制御文字は文字列内に直接書けないため、\n というエスケープ表記に置き換える必要がある」です。JSONがデータ構造の厳密な表現を目的としているため、このようなルールになっています。

JSONファイルを直接編集していて edit_file で詰まることがある方には、「Claudeのedit_fileができない原因と解決策」も参考になると思います。JSONエスケープと改行コードの問題がまとめて解説されています。

また、WSL環境でJSONファイルを扱っている場合、改行コードの混在は /mnt/c 配下のファイルシステム構造に起因することがあります。「WSLで/mnt/cが遅い理由と解決策」で背景ごと理解しておくと、同じトラブルを繰り返しにくくなると思います。

今日できる一歩は、自分が扱っているJSONファイルを開いて「文字列の中に複数行のテキストが入っていないか」を確認することです。もしあれば、body.md への分離を検討してみてください。

JSONに本文を入れるかどうかは、設計の判断の問題でもあります。ファイル構成や役割分担の考え方を整理したい方は、bizinets.bizの判断軸ページが参考になると思います。