Windows 11 における Zendesk CLI (zcli) preview のローカルサーバーアクセス不具合と IPv6 優先度設定による解決

背景

Zendesk アプリ開発においては、公式 CLI ツール「zcli」を用いてローカルでアプリをプレビューする機会が多くあります。本稿では、Windows 11 環境にて zcli themes:preview コマンドによるプレビュー時、CSS などの静的リソースが正しく表示されない現象が発生した事例について、その原因と解決方法を報告します。

OS: Windows 11 Pro (23H2)
本体モデル: Surface Laptop 5

問題の概要

Windows 11 を搭載した開発端末において、zcli themes:preview により起動したプレビューサーバーへ「localhost」でアクセスした際、下記のような現象が再現しました。

• 一部静的リソース（CSS 等）が 404 エラーとなり、画面が正しく表示されない
• ブラウザの開発者ツールでリソース取得失敗が確認できる

同一ネットワーク上の他の端末（Windows 10, macOS 等）では発生せず、当該端末固有の問題であることが判明しました。

調査内容

現象発生端末にて ping localhost を実施したところ、localhost が IPv6 アドレス（[::1]）として解決されていることを確認しました。一方、zcli preview のサーバープロセスは IPv4 アドレス（127.0.0.1）のみでバインドされており、IPv6 アドレスでのアクセスは接続不可となっていたことが原因と推察されます。

• Windows 11 では「localhost」の名前解決時に IPv6（[::1]）が優先される
• zcli preview サーバーは IPv4（127.0.0.1）のみで Listen しているため、リソースへのアクセスに失敗する

なお、React など一部の開発サーバーでは --host 0.0.0.0 などの起動オプションでバインド先を変更できますが、zcli preview には同様のオプションが存在しません。

対応策の検討と実施内容

ネットワークアダプタのIPv6無効化

• Windows のネットワークアダプタ設定より IPv6 を無効化しました。
  → ✖ localhost の名前解決には影響せず、ping localhost の結果は依然として [::1] となりました。

hosts ファイルの編集

• C:\Windows\System32\drivers\etc\hosts の 127.0.0.1 localhost 行のみを有効化しました。
  → ✖ OSレベルで IPv6 が優先され、効果がありませんでした。

IPv6 アドレス選択ポリシーの変更（解決）

• Windows の「アドレス選択ポリシー（Prefix Policy）」を変更し、localhost で IPv4 アドレス（127.0.0.1）が優先されるように設定しました。
  → ⭕ 解決しました。

実施コマンド

管理者権限のコマンドプロンプトで下記を実行しました。

netsh interface ipv6 set prefixpolicy prefix=::1/128 precedence=10 label=0
netsh interface ipv6 set prefixpolicy prefix=::ffff:0:0/96 precedence=50 label=4

その後、PCを再起動しました。

結果

• ping localhost の結果が 127.0.0.1 となり、IPv4 アドレスが優先されるようになりました。
• ブラウザ経由での http://localhost:4567 アクセス時も、全ての静的リソースが正しく取得できるようになりました。
• 本事象は Windows 11 環境特有であり、zcli preview の仕様と Windows のデフォルト設定の組み合わせで発生します。

副作用および留意点

• 本設定変更は localhost に限らず、PC 上の全てのアドレス解決・通信に影響します。IPv4/IPv6 両方のアドレスが割り当てられている場合、IPv4 が優先されやすくなります。

• 通常の開発用途やインターネット利用、一般的な業務システムでは、この変更による影響や体感できる副作用・速度低下は基本的に発生しません。

• ただし、下記のようなケースでは注意が必要です。

  • 社内システムや一部クラウドサービスなど、「IPv6 通信のみ」を前提としている
  • 検証・開発用途で必ず IPv6 で疎通する必要がある
  • 独自に IPv6 通信を強制しているアプリケーションやテストツールを利用している

• これらの特殊なケースを除けば、ほとんどのユーザーや開発環境では実質的な副作用はありません。 もし通信ができなくなる等の問題が発生した場合は、設定は下記コマンドで簡単に元に戻せます。

  netsh interface ipv6 set prefixpolicy prefix=::1/128 precedence=50 label=0
  netsh interface ipv6 set prefixpolicy prefix=::ffff:0:0/96 precedence=35 label=4
  

結論

Windows 11 環境で zcli themes:preview 実行時に localhost アクセスが正常に動作しない場合、IPv6 アドレス選択ポリシーの調整により、問題が解消できることを確認しました。同様の現象でお困りの場合、本稿記載の対応策が参考となれば幸いです。

参考

• Previewing theme changes locally - Zendesk help
• How to prioritise IPv4 over IPv6 on Windows 10 and 11