build-and-deploy

Even Hub G2 アプリを配布用にパッケージ化します。以下の手順に注意深く従い、各段階を検証してから次に進んでください。

パッケージ化のワークフロー

以下の手順を順番に実行してください。

ステップ 1 — app.json の検証

1. プロジェクトのルートにある app.json を見つけます。
2. ファイルを読み込み、すべてのフィールドを以下のフィールドリファレンスに照らして検証します。
3. フィールドが欠落している、型が正しくない、または検証ルールに違反している場合は、正確なエラーを報告して修正します（package_id や name など、重要な値を変更する修正にはユーザーの確認を得てください）。
4. app.json が有効になるまで、次に進まないでください。

ステップ 2 — ビルド

プロジェクトのルートからビルドコマンドを実行します。

npm run build

ビルドが成功し（終了コード 0）、出力フォルダー（通常は dist/）が存在して空でないことを確認します。

ステップ 3 — .ehpk へのパッケージ化

<name> をアプリ名に置き換えて、パックコマンドを実行します。

npx evenhub pack app.json dist -o <name>.ehpk

app.json の name フィールドの値を（小文字に変換し、スペースをハイフンに置き換えて）<name> として使用します。たとえば、name が "Weather Now" の場合は、weather-now.ehpk を使用します。

ステップ 4 — 出力の確認

.ehpk ファイルが作成されたことを確認します。

ls -lh <name>.ehpk

ファイルが見つからない場合は、パックコマンドのエラー出力を確認し、以下のトラブルシューティング表を参照してください。

ステップ 5 — 配布

.ehpk ファイルを Even Hub 開発者ポータルに提出し、審査と公開を依頼します。

---

app.json フィールドリファレンス

特に記載がない限り、すべてのフィールドが必須です。evenhub pack を実行する前に、各フィールドを検証してください。

フィールド	型	必須	検証ルール
package_id	string	はい	リバースドメイン形式（例：com.example.myapp）。小文字の英字と数字のみ使用できます。ハイフン、大文字、アンダースコアは使用できません。ドットで区切られたセグメントが 2 つ以上必要です。各セグメントは小文字の英字で始まり、小文字の英字または数字のみを含む必要があります。
edition	string	はい	"202601" と完全に一致する必要があります。
name	string	はい	最大 20 文字です。
version	string	はい	Semver 形式 x.y.z（ドットで区切られた 3 つの数値部分、例："1.0.0"）。v 接頭辞やプレリリース接尾辞は使用できません。
min_app_version	string	はい	必要な Even Hub アプリの最小バージョンです。例："2.0.0"。
min_sdk_version	string	はい	必要な SDK の最小バージョンです。ビルドに使用する SDK のバージョンと一致させます（現在は "0.0.12"）。
entrypoint	string	はい	ビルド出力フォルダーを基準とした、エントリー HTML/JS ファイルへのパスです。npm run build の実行後、ファイルがビルド出力内に存在している必要があります。
permissions	array	はい	権限オブジェクトの配列です（「権限リファレンス」を参照）。空の [] でもかまいません。キーと値のマップ形式は使用できません。
supported_languages	array	はい	対応言語セットから選択した BCP 47 言語コードの配列です。有効な値：en、de、fr、es、it、zh、ja、ko。

app.json の最小有効例

{
  "package_id": "com.example.weatherapp",
  "edition": "202601",
  "name": "Weather Now",
  "version": "1.0.0",
  "min_app_version": "2.0.0",
  "min_sdk_version": "0.0.12",
  "entrypoint": "index.html",
  "permissions": [],
  "supported_languages": ["en"]
}

---

権限リファレンス

permissions はオブジェクトの配列である必要があります。各オブジェクトには次のフィールドがあります。

フィールド	型	必須	備考
name	string	はい	以下に記載されている有効な権限名のいずれかです。
desc	string	はい	人が読める説明で、1～300 文字です。
whitelist	string[]	network の場合のみ	許可する URL のリストです。name が "network" の場合は必須です。

有効な権限名

• network — 外部ネットワークへのアクセス（whitelist が必要）
• location — デバイスの GPS／位置情報データ
• g2-microphone — G2 グラスのマイク
• phone-microphone — ペアリングされたスマートフォンのマイク
• album — フォトアルバムへのアクセス
• camera — カメラへのアクセス

例

"permissions": [
  {
    "name": "network",
    "desc": "Fetches weather data from the API.",
    "whitelist": ["https://api.weather.com"]
  },
  {
    "name": "g2-microphone",
    "desc": "Enables voice commands for hands-free control."
  }
]

よくある間違い

キーと値のマップ形式は使用しないでください。

// WRONG
"permissions": { "network": ["example.com"] }

// CORRECT
"permissions": [{ "name": "network", "desc": "...", "whitelist": ["example.com"] }]

---

WebView での CORS

Even App は、実際のブラウザーエンジン（Android では Chromium、iOS では WKWebView）内でプラグインを実行します。CORS の制限が完全に適用されます。 app.json のネットワーク許可リストは Even レベルの権限チェックであり、CORS を回避するものではありません。次の両方が必要です。

1. app.json の permissions.network.whitelist にドメインを登録すること、そして
2. リモート API が適切な CORS ヘッダー（Access-Control-Allow-Origin など）を返すこと

呼び出す API が CORS ヘッダーを送信しない場合、ドメインが許可リストに登録されていても、fetch() はネットワークエラーで失敗します。

状況	対処方法
API に CORS ヘッダーがある	app.json にドメインを登録するだけで動作します
API に CORS ヘッダーがない	独自のバックエンド、Cloudflare Worker プロキシ（無料枠）、または CORS に対応したミラーを使用してください
開発サーバー（localhost）が CORS によってブロックされる	vite.config.ts に Vite プロキシを追加してください — 以下を参照

Vite 開発プロキシ

ローカル開発中の CORS を回避するには、Vite プロキシを使用します。

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'https://api.example.com',
        changeOrigin: true,
        rewrite: (p) => p.replace(/^\/api/, ''),
      },
    },
  },
})

このプロキシが機能するのは開発時のみです。本番用の .ehpk では、WebView がリクエストを直接送信します。API に CORS ヘッダーが必要です。そうでない場合は、独自のプロキシ経由でリクエストを送信してください。

無料の CORS プロキシサービスは信頼できません

corsproxy.io、allorigins.win、api.codetabs.com などの公開プロキシは、停止したり、警告なく 403 を返したり、タイムアウトしたりします。アプリが CORS に対応していないサードパーティ API に依存する場合は、独自の Cloudflare Worker（無料枠、セットアップは約 5 分）をデプロイするか、CORS ヘッダーを標準で提供するミラーを探してください。

---

evenhub pack のオプション

npx evenhub pack <app.json> <build-folder> [options]

オプション	説明
-o <file> / --output <file>	出力ファイル名です。指定しない場合は out.ehpk が使用されます。
--no-ignore	ドットファイルや、通常は無視されるその他のファイルをパッケージに含めます。
-c / --check	パッケージ化の前に、Even Hub ストアで package_id が利用可能か確認します。

---

トラブルシューティング

エラー	対処方法
Invalid package id	ドットで区切られたセグメントが 2 つ以上ある、小文字の逆ドメイン形式を使用してください。ハイフン、大文字、アンダースコア、数字で始まるセグメントは使用できません。例：com.example.myapp。
name: must be 20 characters or fewer	app.json の name の値を 20 文字以内に短縮してください。
version: must be in x.y.z format	"1.0.0" のような、3 つの部分からなる数値の semver 文字列を使用してください。"1.0"、"v1.0.0"、プレリリースタグは使用しないでください。
min_app_version: expected string, received undefined	min_app_version は必須です。app.json に追加してください（例："2.0.0"）。
min_sdk_version: expected string, received undefined	min_sdk_version は必須です。app.json に追加してください（例："0.0.12"）。
permissions: each permission must be an object with name and desc keys	permissions は、それぞれに name と desc を含むオブジェクトの配列にする必要があります。上記の Permissions Reference を参照してください。
supported_languages: invalid language	サポート対象の小文字 ISO コード（en、de、fr、es、it、zh、ja、ko）のみを使用してください。
Entrypoint file not found	npm run build の実行後に、app.json の entrypoint がビルド出力フォルダー内に存在するファイルを指していることを確認してください。
Project folder not found	ビルド出力フォルダーが存在しません。まず npm run build を実行してから、evenhub pack を再度実行してください。

---

配布

.ehpk ファイルの検証が完了したら、審査と公開のためにEven Hub 開発者ポータルに提出してください。ポータルではパッケージの検証と互換性チェックが行われ、承認後に Even Hub G2 ユーザーがアプリを利用できるようになります。

---

タスク

$ARGUMENTS