PowerShellでAPIデータをファイルに保存する際、ハングルが文字化けする「二重UTF-8エンコード（Double UTF-8）」現象に苦しんでいる方向けの記事です。私が本番環境で実際に踏み抜いた地雷と、Pythonを使った確実な回避策を共有します。
問題の背景
ある日の運用業務中、社長から「Blogger APIから取得した韓国語の記事本文をバックアップ用のJSONファイルとして保存せよ」との指示が下りました。資本主義社会において、社長からのバックアップ指示は絶対です。私はすぐさまPowerShellスクリプトを書いてAPIを呼び出しました。しかし、APIのレスポンスを受け取り、Out-File -Encoding utf8 を通してファイルに書き出した瞬間、悲劇が起きました。ハングルの3バイト文字がLatin-1として誤解釈され、6バイトの二重UTF-8（Double UTF-8）としてエンコードされてしまったのです。作成したバックアップを検収しようとした社長の目の前で、ハングルがすべて文字化けして表示され、冷や汗が止まりませんでした。
エラーの症状
保存されたJSONファイルを再度読み込んでみると、ハングルが完全に文字化け（mojibake）していました。ファイル内で「사장님（社長）」という単語を検索してもヒット件数は0件。本文のgrepも完全に全滅です。ファイルの中身は íë§ のような、正体不明の文字化けテキストで埋め尽くされていました。
環境
- OS: Windows 11
- Shell: PowerShell 5.1
- Runtime: Python 3.12 / requests 2.31
試してダメだったこと
- -Encoding utf8 の明示： PowerShellのコマンドで明示的にエンコーディングを指定してみましたが、強制的にUTF-8 BOMが付与されたり、二重エンコードが解消されなかったりと、あえなく撃沈しました。
- Python側で utf-8-sig としてデコードを試みる： Out-Fileで出力されたファイルはそのままに、Pythonで読み込む際のエンコーディングを変更してみました。デコード自体は通るものの、本文のハングルは文字化けしたままで、復旧には至りませんでした。
最終的な解決策
正確な原因についてはさらなる調査が必要ですが、現時点で判明している原因は次の通りです。PowerShell 5.1のパイプライン処理が.NET文字列を出力する際、システムロケールを基準に再エンコードを試みます。その過程で、すでにUTF-8であるデータをLatin-1と誤認し、二重エンコードを誘発しているようです。そこで、PowerShellによるファイル出力を完全にバイパスすることにしました。Pythonのrequestsライブラリで直接APIを叩き、Python組み込みのopen関数と json.dump を使って直接ファイルに書き出すようコードを修正したところ、見事に解決しました。
修正後のコード
import requests, json
url = "YOUR_BLOGGER_API_URL"
out_path = "backup.json"
# Pythonで直接APIを叩いてファイルに保存
r = requests.get(url)
with open(out_path, "w", encoding="utf-8") as f:
json.dump(r.json(), f, ensure_ascii=False)検証結果
Pythonでデータを再度フェッチして保存した後、JSONファイルを確認しました。本文内のハングルである「소프트웨어（ソフトウェア）」や「인사이트（インサイト）」などが、文字化けすることなく正常に表示されていることを確認できました。JSONをロードした際も、単一のUTF-8エンコードとして綺麗に読み込めました。
現在のステータス
fixed（解決済み）
同じ問題に直面している方へ
WindowsのPowerShell 5.1環境でAPIのレスポンスをファイルに保存する際、ハングルの文字化けに遭遇したら、シェルのエンコーディング設定をいじって解決しようと消耗するのはやめましょう。シェルのパイプライン処理におけるエンコーディングの仕様上、時間を無駄にする可能性が極めて高いです。最初からPythonやNode.jsなどのバックエンドランタイム側で直接ファイル書き込み（encoding='utf-8'）を行うのが、最も手っ取り早く、かつ確実な解決策です。
Category Coverage Notice
This article follows our label-specific editorial criteria. Details: