この記事について
この記事は、生成AIを活用した自動生成フローで作成しています。WHATWG Encoding StandardとMDNのTextDecoder仕様を参照し、UTF-8分割の比較教材を作成しました。ブラウザー上での操作は未確認です。検証ステータス:📘 仕様・コード静的確認済み/ブラウザー実操作未確認
TextDecoderのstream:trueはなぜ必要?日本語が途中で切れると文字化けする理由
APIから受信したデータを少しずつ読み込むとき、日本語や絵文字が突然「�」に置き換わることがあります。原因の一つは、ネットワークやファイルの分割位置とUTF-8の文字境界が一致しないことです。バイト列の途中で文字を復号し、後から文字列だけを連結しても元には戻りません。
JavaScriptの標準API TextDecoderには、分割されたバイト列を順に復号するためのstream: trueがあります。ブラウザーだけで試せる教材で、失敗する書き方と正しい書き方を並べて確認しましょう。
まず試す:2バイトで区切ってみる
デモには「東京🍣の受付番号」という架空の文字列が用意されています。「前半のバイト数」に2を入力し、「比較する」を押してください。画面には元のUTF-8バイト列、分割後のバイト数、二つの復号結果が表示されます。
| 比較 | 期待される観察 |
|---|---|
| 分割したチャンクをそれぞれ新しいTextDecoderで復号 | 先頭の「東」が途中で切れるため置換文字が入る |
同じTextDecoderでstream:trueを使う | 「東京🍣の受付番号」と一致する |
| 分割位置を文字の境界へ移動 | 個別復号でも正常になる場合がある |
| 分割位置に0や範囲外の値を指定 | 入力エラーを表示する |
「2バイト」の位置は、UTF-8で3バイトになる「東」の途中です。通信処理が文字を意識して分割してくれるとは限らないため、このような境界は特別な例ではありません。なお、これは教材で予想される結果であり、実際のブラウザー操作結果を確認済みとするものではありません。
何が違うのか:バイト列と文字列を区別する
TextEncoderはJavaScriptの文字列をUTF-8のバイト列へ変換します。英数字の多くは1バイト、日本語の漢字は通常3バイト、今回の絵文字は4バイトです。バイト列は通信や読み取りの都合で任意の場所で分割されます。
たとえば「東」はUTF-8でE6 9D B1です。最初のチャンクがE6 9Dで終わると、その時点では文字が完成していません。別々の復号器で処理すると、不完全な部分が置換文字になり、後半のB1を受け取っても復元できません。
stream:trueは、復号器が途中のバイト列を次回のdecodeまで保持するための指定です。通信を開始するフラグではありません。同じ復号器を使い続けること、最後に終了処理を行うことが重要です。
最小コードで比較する
以下は、UTF-8文字の途中で分割する例です。ブラウザーの開発者ツールのConsoleなど、TextEncoderとTextDecoderが利用できる環境を想定しています。
const bytes = new TextEncoder().encode("東京");
const chunks = [bytes.slice(0, 2), bytes.slice(2)];
// 誤りやすい例:チャンクごとに復号器を作り直す
const broken = chunks.map(c => new TextDecoder().decode(c)).join("");
// 正しい例:同じ復号器で未完成のバイトを持ち越す
const decoder = new TextDecoder("utf-8");
const correct = chunks.map(c => decoder.decode(c, {stream: true})).join("")
+ decoder.decode(); // 最後に残りを確定させる
console.log({broken, correct});
期待結果は、correctが「東京」と一致し、brokenには置換文字が含まれることです。教材の完全版では分割位置を入力できるため、2以外の値でも観察できます。
処理の流れを図で理解する
次の図は、同じバイト列でも復号器の状態管理によって結果が変わる理由を示しています。
flowchart TD
A[UTF-8バイト列] --> B[任意の位置で2分割]
B --> C[各チャンクを別々にdecode]
B --> D[同じdecoderでstream true]
C --> E[不完全な文字が置換され得る]
D --> F[未完成のバイトを次へ保持]
F --> G[最後にdecodeで終了]
G --> H[元の文字列に復元]
注意したいのは、stream:trueを指定していても毎回new TextDecoder()してしまうと、持ち越す状態が失われることです。反対に、チャンクが常に文字境界で分かれていれば、誤った実装でも一見正常に見えます。だからこそ、文字の途中で切れる条件を試験に含めます。
実務ではどこで使うか
典型例はfetch()で取得したレスポンスのReadableStreamをreader.read()で繰り返し読む処理です。返されるUint8Arrayの境界は、文章の改行やUTF-8文字の境界と一致する保証がありません。ログの逐次表示、チャットのストリーミング応答、ファイルの分割読み取りで、同じ注意が必要です。
ブラウザーで読み取りストリームを文字列にするなら、TextDecoderStreamという別の標準APIも選択肢になります。既存の処理がUint8Arrayを直接扱っているなら、TextDecoderのstream:trueで状態を保持する方法が理解しやすいでしょう。いずれも、途中でチャンクが切れたこと自体を通信エラーと決めつけないことが大切です。
条件を変えて失敗原因を切り分ける
まず分割位置を2にして差が出ることを確認し、次に3へ変更します。「東」の3バイトを受け取った後なら、前半だけで文字が完成するため、個別復号の結果も一致するはずです。さらに絵文字の途中で分割すれば、同じ問題を4バイト文字で観察できます。
| 症状 | 確認箇所 | 対処 |
|---|---|---|
| デモのボタンが動かない | app.jsの読み込み、ブラウザーConsole | 同じフォルダにHTMLとJSを配置 |
| 両方式が同じ結果 | 分割位置が文字境界か | 2バイトで分割して再比較 |
| stream側も置換文字になる | 入力バイト列の破損、復号器の作り直し | 元のバイト列と同一インスタンス利用を確認 |
| 最後の文字が出ない | decode()による終了処理 | すべてのチャンク処理後にflush |
| 画面に入力エラー | 分割位置が0・範囲外・整数以外 | 1以上で最大値以下の整数を指定 |
個人情報を含む通信ログをそのまま教材へ貼り付ける必要はありません。まず架空の文字列で復号処理を検証し、実データを扱う際は認証情報・本文・URLパラメーターを公開しないようにしてください。
まとめ
UTF-8のバイト列を分割して読むとき、分割位置は文字の境界とは限りません。TextDecoderのstream:trueは不完全な文字のバイト列を次回へ持ち越し、最後のdecode()で復号を終了します。通信の不具合だと思った文字化けも、復号器の使い方を見直すことで切り分けられます。
