【EC-CUBE4.3】mock-package-apiで「/packages.json」が500エラーになる原因と解決方法

EC-CUBEのプラグイン開発で mock-package-api を使って、ローカルに置いた .tgz プラグインパッケージを /packages.json で読み込ませようとしたところ、500エラーでつまずいたので原因と対処法を共有します。

---

💥 起きた問題

以下のように mock-package-api を起動した後…

docker run -d --rm \
  -v $(pwd)/repos:/repos \
  -e MOCK_REPO_DIR=/repos \
  -p 9999:8080 \
  eccube/mock-package-api

http://host.docker.internal:9999/packages.json にアクセスすると、こんなエラーが返ってきました。

{
  "status": 500,
  "error": "Internal Server Error",
  "message": "Could not read from \"tgz:file:///repos/OrderInquiry.tgz!/composer.json\" because it is not a file."
}

---

🔍 原因

.tgz の中の構造が 「ディレクトリごと圧縮」されていた ため、
mock-package-api が探す composer.json の位置とズレていた。

❌ NGな構造（tar -tzf の結果）

OrderInquiry/
OrderInquiry/composer.json
OrderInquiry/...

mock-package-api は OrderInquiry.tgz!/composer.json を探すため、
この構造だと見つけられずに 500 エラーになります。

---

✅ 正しい構造（flat構造）

以下のように .tgz の中に composer.json が 直に存在している必要があります。

✅ OKな構造

composer.json
PluginManager.php
Resource/config/plugin.yml
...

---

🛠 解決方法：ディレクトリの中身だけを圧縮

# plugins ディレクトリ内の OrderInquiry の中に移動
cd app/Plugin/OrderInquiry

# repos フォルダがなければ作る
mkdir -p ../../repos

# ディレクトリではなく「中身」だけを圧縮
tar --exclude-vcs -czvf ../../repos/OrderInquiry.tgz *

---

🚀 再確認

curl http://host.docker.internal:9999/packages.json

以下のようなレスポンスが返ってくれば成功！

{
  "OrderInquiry": {
    "version": "1.0.0",
    "file": "/OrderInquiry.tgz"
  }
}

---

📌 補足

• composer.json には最低限、以下のような情報が必要です：

{
  "type": "eccube-plugin",
  "extra": {
    "code": "OrderInquiry",
    "version": "1.0.0"
  }
}

• plugin.yml は mock-package-api の動作には必須ではないが、プラグインの定義としてはあった方がよい

---

🙏 まとめ

• .tgz の中身は「1階層にまとめないといけない」
• mock-package-api は .tgz の直下に composer.json がある前提で動く
• tar コマンドで中身だけを圧縮すれば解決！

---

🔗 参考

• EC-CUBEプラグイン仕様

---

ちゃんと公式ドキュメントを見ていなかったのが原因ですが、万が一同じところでハマった方の参考になれば幸いです 🙌

※ この投稿は、ChatGPTにひな型を作ってもらってます。