macOS zip コマンドで文字化けが直らない原因と対処

ターミナルで zip -r -X を実行したのに、Windows で解凍すると日本語ファイル名がまだ文字化けしている。
「__MACOSX を除去すれば直る」と書かれた記事を試したが、やはり直らない。
原因は macOS 標準の zip コマンド自体にあります。
このコマンドは __MACOSX フォルダの除去はできますが、日本語ファイル名のエンコーディング変換には非対応です。
brew版 zip 3.0 の -UN=UTF8 オプションを使うと、この問題を根本から解消できます。
診断の視点と具体手順をまとめます。

macOS 標準 zip が文字化けを直せない理由

macOS の zip コマンドは /usr/bin/zip に配置されていて、Apple がカスタマイズしたビルドです。
バージョン表記が 3.0 に見えても、-UN=UTF8 オプションはビルドから除外されています。

ZIP 形式で日本語ファイル名を Windows で正しく表示するには、ZIPヘッダに Unicode path extra field を書き込む必要があります。
これはファイル名を UTF-8 エンコードで保持する付加情報で、Windows の解凍ツールや 7-Zip はこのフィールドを優先して読みます。
macOS 標準の zip にはこのフィールドを書き込む機能がない。
ファイル名のエンコーディングは変換されないまま圧縮されます。

Mac はファイル名を UTF-8 で管理しますが、Windows の多くの解凍ツールは ZIP 内のファイル名を Shift_JIS として読もうとします。
UTF-8 のバイト列を Shift_JIS として解釈すると、「縺ゅ▲縺」のような記号の羅列。これが文字化けの正体です。
この文字化けを防ぐためには、ZIP に「このファイル名は UTF-8 だ」という情報を明示的に付与する必要があります。

-X フラグの役割は、Apple 固有の拡張属性（XAttr）の除去です。
__MACOSX フォルダを圧縮対象から外すことも含みますが、文字コードのエンコーディング変換とは別の機能です。
-X を付けても日本語ファイル名の文字化けには影響しません。

Finder の「圧縮」メニューは手軽ですが、__MACOSX フォルダを生成するうえ、エンコーディング変換もしません。
Web制作の納品には向きません。

「直らない」と感じたときは、2点を確認します。

1. 文字化けの原因が __MACOSX フォルダか、ファイル名のエンコーディングか
2. which zip で使用中の zip が標準版か brew版かを確認する

brew版 zip 3.0 の -UN=UTF8 の使い方

-UN=UTF8 オプションを指定すると、各ファイル名を UTF-8 エンコードで Unicode path extra field に書き込みます。
Windows の解凍ツールや 7-Zip はこのフィールドを優先して読むため、日本語ファイル名がそのまま表示されます。
標準 zip にはこの書き込み機能がないため、brew版 zip 3.0 が必要になります。

過去の納品作業で、標準 zip で作った ZIP を Windows で解凍したところ、日本語ファイル名がすべて文字化けしていました。
-X フラグを追加しても変わらず、brew版 zip 3.0 を導入して -UN=UTF8 を付けた時点で解消しました。

__MACOSX と DS_Store の除去を合わせると、1コマンドで完結します。

zip -r -UN=UTF8 -x "__MACOSX/*" -x "*.DS_Store" output.zip ./target-dir/

ソースコードを含む場合は .git ディレクトリも除外します。

zip -r -UN=UTF8 -x "__MACOSX/*" -x "*.DS_Store" -x "*.git/*" output.zip ./target-dir/

Windows で解凍して日本語ファイル名が表示されることを確認してから納品しています。

現行の Windows 標準「エクスプローラーで展開」や 7-Zip であれば、-UN=UTF8 付きの ZIP を問題なく展開できます。
古い Shift_JIS 専用ツールとの相性は別の話ですが、現在の納品先で使われることはほぼありません。

-UN=UTF8 は ZIP 作成時に指定するオプション。
ZIP 内のファイル名エントリは作成時に確定するため、後から変換する方法はありません。
文字化けが残っている場合は brew版 zip で作り直します。

brew版 zip のインストールから納品コマンドまで

Homebrew が入っていれば導入は 1 コマンドです。

brew install zip

インストール後、バージョンとパスを確認します。

zip --version
which zip

Zip 3.0 と表示されれば brew版が動いています。
Apple Silicon Mac は /opt/homebrew/bin/zip、Intel Mac は /usr/local/bin/zip が返れば brew版です。
/usr/bin/zip が返る場合は macOS 標準が使われていて、Homebrew の PATH が通っていない可能性があります。
Apple Silicon Mac では .zshrc に次の行を追加し、ターミナルを再起動します。

eval "$(/opt/homebrew/bin/brew shellenv)"

設定が整ったら、納品用 ZIP はこのコマンドです。

zip -r -UN=UTF8 -x "__MACOSX/*" -x "*.DS_Store" -x "*.git/*" 納品.zip ./target/

Windows で解凍し、日本語ファイル名を目視確認してから納品します。
GUI が必要な場面では Keka が選択肢です。
Keka の ZIP 出力は UTF-8 エンコードを自動付与しますが、シェルスクリプト組み込みには brew版 zip が向いています。

ZIP 納品全体のワークフローは 納品ZIPの運用ルールと文字化け事故を防ぐワークフロー にまとめています。
MacからWindowsへのZIP送付で気をつけることの全体像は MacからWindowsにZIPを送るときに気をつけたいポイントと対策 も参照してください。

まとめ

• macOS 標準 zip は日本語ファイル名の UTF-8 変換に非対応
• -X フラグは __MACOSX 除去のみ。文字化け解消とは別の機能
• brew install zip でbrew版 3.0 を入れて -UN=UTF8 を使う
• -x "__MACOSX/*" と -x "*.DS_Store" を合わせて納品用の1コマンドを完成させる

コーディング代行や実装判断で詰まったら Build に振ってください。