JSONエスケープ変換の仕組み|一行の文字列に変換する方法

複数行のJSONをCLI引数や.envファイルの値にそのまま貼り付けると壊れてしまうのは、バックスラッシュ・ダブルクォート・改行というごく少数の文字が、貼り付け先の文法と衝突するからです。
これらの文字をそれぞれ決められたエスケープシーケンスに置き換えれば、元の内容をそのまま含んだ1行の安全な文字列になります。この記事では、その置換ルールを文字単位で説明します。
まとめ ① JSONをCLI引数・.envの値にそのまま入れると、バックスラッシュ・ダブルクォート・改行が貼り付け先の文法と衝突して壊れます。 ② 「JSONエスケープ」モードはJSON.parseで妥当性を検証したうえで1行に圧縮し、「Rawテキストエスケープ」モードは検証せずに入力をそのままエスケープします。 ③ ダブルクォート・改行・タブは既定でオン、シングルクォートは既定でオフなので、チェックボックスを変えると同じ入力でも別の文字列が出力されます。
CLI引数や.envの値にJSONをそのまま入れると、なぜ壊れるのか
API応答や設定ファイルから受け取ったJSONを、.envファイルのAPP_CONFIG=の後ろにそのまま貼り付ける状況を考えてみます。元のJSONは、人間が読みやすいように改行とインデントが入った複数行のテキストです。
このテキストを1行の値が必要な場所にそのまま入れると、3か所で壊れます。
- 改行:
.envファイルやシェル変数は1行を1つの値として読みます。値の途中に実際の改行があると、その行で値が切れてしまいます。 - ダブルクォート: 値全体をダブルクォートで囲むのが慣例ですが、JSONの内部にもダブルクォートが大量に入っています。パーサーは内側のクォートに出会った瞬間に値を終わりと解釈します。
- シングルクォートで囲んだCLI引数: JSONの文字列値の中にアポストロフィ(')があると、POSIXシェルはシングルクォートの中でシングルクォートをエスケープする方法がないため、その地点で引数が閉じてしまいます。
そのため、JSONを1行の文字列として収める必要がある貼り付け先——CLI引数、.envの値、別のJSONにネストする文字列フィールド、ソースコードの文字列リテラル——は、共通して同じルールを要求します。
改行やタブといった制御文字は目に見えるシーケンスに置き換え、区切りとして使われる引用符と、エスケープ自体に使われるバックスラッシュの前には、バックスラッシュをもう1つ付けて「この文字は文法記号ではなく、ただのデータです」と示す必要があります。
ツールを使わずに手でエスケープする方法
エスケープのルールは特定のプログラムだけが知っている秘密ではなく、JSON.stringifyをはじめ、ほとんどの言語が従っている共通の文字置換表です。
ブラウザの開発者ツールのコンソールで以下のコードを実行すると、この記事で説明しているツールと同じ結果を手元で再現できます。
JSONの文法を検証しながら圧縮までしたい場合は、こうします。
// ステップ1: JSON文法の検証 + 1行に圧縮(インデント・改行を除去)
const minified = JSON.stringify(JSON.parse(rawInput));
// ステップ2: 文字置換。バックスラッシュを最初に置き換えることで、
// 後から追加するバックスラッシュが再度置換されるのを防ぎます。
const escaped = minified
.replace(/\\/g, "\\\\") // バックスラッシュ → \\
.replace(/"/g, '\\"') // ダブルクォート → \" (オプション)
.replace(/\n/g, "\\n") // 改行 → \n (オプション)
.replace(/\t/g, "\\t"); // タブ → \t (オプション)
rawInputが有効なJSONでなくてもよい場合、つまりログの断片や一般のテキストをそのままエスケープしたい場合は、ステップ1を飛ばして元の文字列にステップ2の置換チェーンだけを適用します。
これが「Rawテキストエスケープ」モードがやっていることのすべてです。
こうして得た結果をダブルクォートで囲んでCLI引数や.envの値の位置に貼り付ければ、元のJSONの意味をそのまま保ったまま1行で渡せます。
当社の無料ツール「JSONエスケープ変換ツール」で確認する。
JSONはパース検証後に一行へ圧縮し、通常のテキストは検証せずそのままエスケープします。インストールも会員登録も不要で無料で使えます。

よく混同しやすいポイント
2つのモードの違いを表にまとめると次のようになります。
| 項目 | JSONエスケープモード | Rawテキストエスケープモード |
|---|---|---|
| JSON.parse検証 | します(失敗時はエラー表示) | しません |
| 圧縮(改行・インデントの除去) | JSON.stringifyで圧縮されます | 元のまま保持されます |
| 無効なJSON入力 | 「正しいJSON形式ではありません」エラー | エラーなしでそのまま処理 |
| 適用対象 | 有効なJSONテキストのみ | どんなテキストでも |
チェックボックスをオン・オフしても結果が変わらない理由
エスケープオプションのチェックボックス4つのうち、実際に結果を変える組み合わせはモードによって異なります。
JSONエスケープモードでは、入力がまずJSON.stringifyを1回通りますが、この段階でJSON文法そのものが文字列値の中の改行・タブをすでに\n、\tのような2文字のシーケンスに置き換えています。
そのため、後に続く「改行エスケープ」と「タブ文字エスケープ」のチェックボックスは、JSONモードではオンにしてもオフにしても結果が変わりません。置き換えるべき実際の改行・タブの文字がすでに残っていないからです。
ダブルクォート・シングルクォート・Rawモードは挙動が異なります
逆に「ダブルクォートエスケープ」はJSONモードでも効果があります。キーと値を囲む構造上のダブルクォートは、JSON.stringifyがそのまま残しておくからです。
「シングルクォートエスケープ」もJSON文法にはない文字なので、JSON.stringifyは手を付けません。そのため、値の中にアポストロフィがあればチェックボックスの状態によって結果が変わります。
RawテキストエスケープモードではJSON.stringifyを通さず入力文字をそのまま走査するので、4つのオプションすべてがオン・オフどおりに結果へ反映されます。
なお、JSONモードはJSON.parseが作った値を再びJSON.stringifyでシリアライズする方式なので、1.0のような意味のない小数点が1に変わるなど、元の表記が多少変わることがあります。文字どおりの表記を保つ必要があるなら、Rawモードを使うほうが安全です。
「正しいJSON形式ではありません」エラーが出る場合
JSON.parseが入力をJSON文法として解釈できなかったときにこのエラーが表示されます。よくある原因は次のとおりです。
- 最後の項目の後ろにカンマが残っている場合(トレーリングカンマ)
- キーや文字列値をシングルクォートで囲んでいる場合(JSONはダブルクォートのみ許可)
- キーをクォートなしで書いている場合
- JSONにはないコメント(
//、/* */)が混じっている場合 - 開き括弧と閉じ括弧の数が合っていない場合
これらのいずれかに当てはまると、JSONモードは結果を作らずエラーだけを表示します。文法を直したくない場合はRawテキストエスケープモードに切り替えれば、検証なしでそのままエスケープされます。
まとめ
- バックスラッシュは常に、ダブルクォート・改行・タブは既定値で、シングルクォートはオプションをオンにしないとエスケープされません。
- JSONエスケープモードは
JSON.parseで検証し圧縮までしますが、その過程で文字列値の中の改行・タブがすでに\n、\tに変わっているため、該当するチェックボックスはJSONモードでは効果がありません。 - Rawテキストエスケープモードは検証も圧縮もせず入力文字をそのまま走査するので、4つのオプションすべてが結果に反映され、JSONではないテキストにも使えます。
- 「正しいJSON形式ではありません」エラーは、トレーリングカンマ、シングルクォート、クォートなしのキーといったJSON文法違反が原因です。
- 同じルールは
JSON.stringifyと正規表現の置換チェーンだけでも自分で再現できます。
JSONはパース検証後に一行へ圧縮し、通常のテキストは検証せずそのままエスケープします。インストールも会員登録も不要で無料で使えます。
よくある質問
JSONエスケープとRawテキストエスケープは、どちらを使えばいいですか?
入力が有効なJSONで、構文が正しいかを確認しながら圧縮まで行いたい場合は、JSONエスケープモードを使います。
有効なJSONでない場合(ログの断片、コードの一部、構文が壊れたJSON)や、元の改行・インデントは圧縮せず、エスケープだけを行いたい場合は、Rawテキストエスケープモードを使います。
結果にバックスラッシュが2つ重なって出てくるのですが、エラーですか?
エラーではありません。エスケープシーケンス自体がバックスラッシュ(\)で始まるためです。
元のテキストにすでにバックスラッシュがあった場合、そのバックスラッシュもエスケープの対象となって\\に変わり、続く文字(たとえばダブルクォート)までエスケープされると、バックスラッシュが連続して見えることがあります。それぞれのバックスラッシュは、それぞれ1つのエスケープを表している正常な結果です。
シングルクォートがデフォルトでエスケープされないのはなぜですか?
JSONの構文では文字列をダブルクォートでしか囲まず、シングルクォートには何の意味も持たせていないからです。
そのため、ダブルクォート・改行・タブはデフォルトでオンになっていますが、シングルクォートは値をシングルクォートで囲むシェルスクリプトなど、特定の用途でのみ必要になるため、デフォルトではオフになっています。必要な場合はチェックボックスをオンにしてください。
変換した結果を.envやCLIの引数に入れるとき、引用符は自分で付ける必要がありますか?
はい。このツールは文字列内部の文字だけを置換するもので、値全体を囲む外側の引用符は追加しません。.envファイルやCLIの引数に入れるときは、変換した結果をダブルクォート(またはシングルクォート)で自分で囲まないと、1つの値として認識されません。
この記事は韓国語の原文をもとに作成しています。 韓国語の原文を読む