Base64 エンコード／デコード：UTF-8 のテキストを文字化けさせない

Base64 が本当に必要な場面

ASCII しか受け付けないフィールドに非 ASCII のテキストを入れたいときです。HTTP ヘッダー、設定値、印字可能文字だけを許すプロトコルのフィールドなどが該当します。Base64 は任意のバイト列を安全な64文字のアルファベットに対応させます。

受け取った Base64 が、読める UTF-8 テキストなのか、もともとバイナリの乱数なのかを判断したいときです。デコード結果が � だらけなら、元のバイト列が UTF-8 ではない可能性が高いです。

JWT、Basic 認証ヘッダー、data URL のペイロードを調べるときです。これらのペイロードは Base64 または Base64URL なので、まずデコードしてから読む必要があります。JWT は Base64URL を使い、文字集合とパディングの規則が少し異なります。

• ASCII しか許さないヘッダーや設定値に非 ASCII のテキストを入れる
• 受け取った Base64 が読めるテキストかどうか確かめる
• JWT、Basic 認証ヘッダー、data URL のペイロードを調べる
• ASCII しか通らない経路で短いテキストを記録する

失敗しないための手順

JavaScript の文字列をそのまま btoa() に渡さないでください。btoa() は各文字が 0–255 の範囲にあるバイナリ文字列しか受け付けず、それ以外では InvalidCharacterError を投げます。正しい順序は、TextEncoder で UTF-8 のバイト列にしてから btoa()、デコードは atob() でバイト列を得て TextDecoder('utf-8') で戻します。

サイズは約3割増えます。Base64 は3バイトを4つの ASCII 文字にするため、長さは 4/3 になります。バイト数が3で割り切れない場合は末尾に = が付きます。UTF-8 では、日本語の1文字は通常3バイトで約4文字になり、絵文字は通常4バイトでパディングを含めて約8文字になります。これは圧縮ではなくエンコードのオーバーヘッドです。

デコード時に空白は無視されますが、Base64 のアルファベット以外の文字があるとエラーになります。余計な記号が混ざっている場合は、先に取り除いてください。

UTF-8 ではない Base64 をデコードすると �（U+FFFD）になります。ツールの不具合ではなく、元のバイト列が正当な UTF-8 ではないだけです。画像や圧縮ファイルは、そもそもテキストとしてデコードするものではありません。

URL に入れる場合は Base64URL に切り替えてください。+ を -、/ を _ に変え、末尾の = を削除します。クエリ文字列では、フォームの規則により + が空白として解釈されることがあり、/ はパスの区切りと衝突する可能性があります。

最後に、Base64 は暗号化ではありません。鍵がなく、誰でもデコードできます。パスワードやトークンを「隠す」用途に使っても、外側が変わるだけです。機密性が必要なら AES-GCM、完全性が必要なら署名かハッシュを使ってください。

• btoa() の前に TextEncoder、atob() の後に TextDecoder
• サイズは約 4/3 になり、末尾に = が付く
• UTF-8 でないバイト列は � になる
• URL では Base64URL（- と _、末尾の = なし）

代替手段と限界

バイナリファイルはテキスト用のツールで変換しないでください。コマンドラインの base64、macOS の base64 -i、Windows の certutil -encode、またはコードで ArrayBuffer を読む方法なら、バイト列をそのまま保てます。

機密性には WebCrypto の AES-GCM、認証には HMAC か公開鍵署名を使います。Base64 はバイト列を文字として運ぶだけで、安全性は提供しません。

このツールはテキスト専用です。エンコード時は入力を UTF-8 として解釈し、デコード時は UTF-8 として復元するため、バイナリのバイト列は保持できません。ストリーム処理もないため、非常に大きな入力はメモリを多く使います。

• バイナリファイル → コマンドラインの base64 か ArrayBuffer
• 機密性 → AES-GCM
• 完全性 → 署名かハッシュ
• テキスト専用。バイナリもストリーム処理も不可