harmonyos-build-deploy

HarmonyOS のビルドとデプロイ

HarmonyOS アプリケーションのビルド、クリーン、パッケージ化、インストールを行うための完全なワークフローです。

最初に行うこと：ユーザーに操作を確認する

重要： ビルドまたはデプロイ操作を実行する前に、ユーザーが実行したい具体的な操作を確認してください。次の中から選んでもらいます。

操作	説明
ビルド成果物をクリーンする	前回のビルドキャッシュと出力を削除します
依存関係をインストールする	ohpm を使用してプロジェクトの依存関係をインストールします
プロジェクトをビルドする	hvigorw を使用して HAP／APP パッケージをビルドします
デバイスにインストールする	hdc を使用してアプリをデバイスにインストールします
全工程を実行する	クリーン → 依存関係をインストール → ビルド → デバイスにデプロイ

最初に確認する理由：

• 状況によって必要な操作が異なります（例：インクリメンタルビルドとクリーンビルド）
• 不要で時間のかかる操作を避けられます
• ユーザーがワークフローを制御できます
• 誤ってデバイスにインストールするのを防げます

ユーザーの回答後：

• 選択された操作のみを実行します
• 進行状況と結果を明確に報告します

クイックリファレンス

# Build complete app (incremental)
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon

# List connected devices (returns UDID)
hdc list targets

注： ビルド出力先は outputs/ です。デバイスへのインストールについては、プッシュとインストールを参照してください。

ワークフロー

重要： ビルド、クリーン、デプロイの操作には時間がかかります（ビルドは約30秒、ファイル転送は約20秒）。タイムアウトを避けるため、これらのワークフローは必ずサブエージェントに委任してください。これにより、エラー処理が改善され、ユーザーに進行状況をより明確に報告できます。

クリーンビルドとデプロイ

次の手順をサブエージェントに委任します。

1. クリーン：hvigorw clean --no-daemon
2. 依存関係をインストール：ohpm install --all
3. ビルド：hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon
4. デバイスにデプロイ（下記のプッシュとインストールを参照）
5. 起動：hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
6. 詳細を添えて、成功または失敗を報告

デプロイのみ（再ビルドなし）

次の手順をサブエージェントに委任します。

1. AppScope/app.json5 を読み取り、bundleName を取得
2. outputs/ に既存のビルド出力があるか確認します。空または存在しない場合は、各モジュールのビルドディレクトリ（{srcPath}/build/default/outputs/default/*-signed.*）から署名済みの HAP／HSP を outputs/ に収集します。詳細は module-discovery.md を参照してください。
3. デバイスにデプロイ（下記のプッシュとインストールを参照）
4. 起動：hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
5. 詳細を添えて、成功または失敗を報告

アプリのキャッシュ／データをクリーンする

サブエージェントに委任します。

1. キャッシュをクリーン：hdc -t <UDID> shell "bm clean -n <bundleName> -c"
2. データをクリーン：hdc -t <UDID> shell "bm clean -n <bundleName> -d"
3. 成功または失敗を報告

ビルドコマンド（hvigorw）

インクリメンタルビルド（デフォルト）

通常の開発では、変更されたモジュールのみを再ビルドするインクリメンタルビルドを使用します。

# Build complete app (incremental)
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon

単一モジュールのビルド

特定のモジュールのみをビルドして、反復を高速化します。

# Build single HAP module
hvigorw assembleHap -p module=entry@default --mode module -p buildMode=release --no-daemon

# Build single HSP module
hvigorw assembleHsp -p module=my_feature@default --mode module -p buildMode=release --no-daemon

# Build single HAR module
hvigorw assembleHar -p module=library@default --mode module -p buildMode=release --no-daemon

# Build multiple modules at once
hvigorw assembleHsp -p module=module1@default,module2@default --mode module -p buildMode=release --no-daemon

モジュール名の形式： {moduleName}@{targetName}

• moduleName：モジュールのディレクトリ名（例：entry、my_feature）
• targetName：モジュールの build-profile.json5 で定義されたターゲット（通常は default）

単一モジュールのビルドを使用する場合：

• 特定のモジュールを開発／デバッグするとき
• 反復中のビルド時間を短縮するとき
• モジュールを分離して変更をテストするとき

注： 単一モジュールのビルド後も、インストール用にアプリケーション全体をパッケージ化するには assembleApp を実行する必要があります。

クリーンビルド（必要な場合）

次の場合にのみ、クリーンビルドを実行します。

• プロジェクトを初めてビルドするとき
• 原因不明のビルドエラーが発生したとき
• build-profile.json5 または SDK バージョンを変更した後
• 依存関係の解決で問題が発生したとき

# Clean build artifacts
hvigorw clean --no-daemon

# Deep clean (for dependency issues)
ohpm clean && ohpm cache clean
ohpm install --all
hvigorw --sync -p product=default -p buildMode=release --no-daemon
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon

依存関係のインストール（ohpm）

# Install all dependencies (after clean or first clone)
ohpm install --all

# With custom registry
ohpm install --all --registry "https://repo.harmonyos.com/ohpm/"

プロジェクトの同期

build-profile.json5 または oh-package.json5 を変更した後にのみ必要です。

hvigorw --sync -p product=default -p buildMode=release --no-daemon

ビルドパラメーター

パラメーター	説明
-p product={name}	build-profile.json5 で定義された対象製品
-p buildMode={debug|release}	ビルドモード
-p module={name}@{target}	--mode module を指定した対象モジュール
--mode project	プロジェクト内のすべてのモジュールをビルド
--mode module	特定のモジュールのみをビルド
--no-daemon	デーモンを無効化（CI での使用を推奨）
--analyze=advanced	ビルド分析を有効化

ビルド出力

ビルド出力先：outputs/

outputs/
├── entry-default-signed.hap
└── *.hsp

モジュールの種類

種類	拡張子	説明
HAP	.hap	Harmony Ability Package — アプリケーションのエントリーモジュール
HSP	.hsp	Harmony Shared Package — 動的共有ライブラリ
HAR	.har	Harmony Archive — 静的ライブラリ（HAP にコンパイルされます）
APP	.app	完全なアプリケーションバンドル（すべての HAP + HSP）

モジュールの確認

モジュールはプロジェクトルートの build-profile.json5 で定義されています。モジュールの種類は {module}/src/main/module.json5 の type フィールドで決まります。

type の値	モジュールの種類	ビルドコマンド
"entry" / "feature"	HAP	assembleHap
"shared"	HSP	assembleHsp
"har"	HAR	assembleHar

モジュールのビルド出力先：{srcPath}/build/default/outputs/default/

モジュールの詳細な確認方法、ビルド出力の構成、不要なモジュールの処理については、references/module-discovery.md を参照してください。

デバイスへのインストール（hdc）

hdc（HarmonyOS Device Connector）は、Android の adb と同様の、デバイス通信用のコマンドラインツールです。

デバイスの確認

hdc list targets              # List connected devices (returns UDID)
hdc -t <UDID> shell "whoami"  # Test connection

転送とインストール

# Create temp directory on device (Git Bash compatible)
# If you use Git Bash on Windows, disable MSYS path conversion for hdc commands.
export MSYS_NO_PATHCONV=1

INSTALL_DIR="//data/local/tmp/install_$(date +%s)"
hdc -t <UDID> shell "mkdir -p $INSTALL_DIR"

# Push files one-by-one to explicit remote file paths (most reliable on Git Bash)
for f in outputs/*.hap outputs/*.hsp; do
    [ -f "$f" ] && hdc -t <UDID> file send "$f" "$INSTALL_DIR/$(basename "$f")"
done

# Install (reinstall) HSPs first, then the HAP
for f in outputs/*.hsp outputs/*.hap; do
    [ -f "$f" ] && hdc -t <UDID> shell "bm install -p $INSTALL_DIR/$(basename \"$f\") -r"
done

# Clean up temp directory
hdc -t <UDID> shell "rm -rf $INSTALL_DIR"

確認と起動

# Check installation
hdc -t <UDID> shell "bm dump -n <bundleName>"

# Launch app (default ability)
hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"

アンインストール

hdc -t <UDID> shell "bm uninstall -n <bundleName>"

hdc コマンドリファレンス

コマンド	説明
hdc list targets	接続されているデバイスを一覧表示
hdc -t <UDID> shell "<cmd>"	デバイス上でシェルコマンドを実行
hdc -t <UDID> file send <local> <remote>	ファイル／ディレクトリをデバイスに転送
hdc -t <UDID> file recv <remote> <local>	ファイル／ディレクトリをデバイスから取得
hdc kill	hdc サーバーを終了
hdc start	hdc サーバーを起動
hdc version	hdc のバージョンを表示

バンドルマネージャー（bm）

hdc -t <UDID> shell "bm ..." を使って実行します。

コマンド	説明
bm install -p <path>	ディレクトリからインストール（すべての HAP/HSP）
bm install -p <file.hap>	単一の HAP ファイルをインストール
bm install -r -p <path>	再インストール（既存のものを置き換え、データは保持）
bm uninstall -n <bundleName>	アプリケーションをアンインストール
bm dump -n <bundleName>	パッケージ情報を表示
bm dump -a	インストール済みのパッケージをすべて一覧表示
bm clean -n <bundleName> -c	アプリケーションのキャッシュを消去
bm clean -n <bundleName> -d	アプリケーションのデータを消去

Ability Assistant（aa）

hdc -t <UDID> shell "aa ..." を使って実行します。

コマンド	説明
aa start -a <ability> -b <bundle>	指定した Ability を起動
aa force-stop <bundleName>	アプリケーションを強制停止

トラブルシューティング

エラー	原因	解決策
version code not same	出力先にある HSP が build-profile.json5 に含まれていない	インストール前に不要な HSP ファイルを削除してください（module-discovery.md を参照）
install parse profile prop check error	署名とプロファイルの不一致	build-profile.json5 の署名設定を確認してください。bundleName が app.json5 と一致すること、および証明書の有効期限が切れていないことを確認してください
install failed due to older sdk version	デバイスの SDK がアプリの compatibleSdkVersion より古い	デバイスを更新するか、compatibleSdkVersion を下げてください
デバイスが見つからない	接続の問題	USB 接続を確認してください。開発者向けオプション（ビルド番号を 7 回タップ）と USB デバッグを有効にし、hdc kill && hdc start を実行してください。別の USB ポート／ケーブルも試してください
signature verification failed	証明書が無効または期限切れ	DevEco Studio で証明書を再生成してください。有効期間を確認し、ビルドの種類に合った署名設定になっていることを確認してください

主な設定ファイル

ファイル	説明
AppScope/app.json5	アプリのメタデータ（bundleName、versionCode、versionName）
build-profile.json5	モジュール一覧、プロダクト、署名設定
{module}/src/main/module.json5	モジュール設定（abilities、権限）
{module}/oh-package.json5	モジュールの依存関係

参考ファイル

• モジュールの検出とビルド出力：references/module-discovery.md - モジュールの定義、種類の識別、ビルド出力先、不要なモジュール
• インストールガイド全文：references/device-installation.md - バージョン確認スクリプトとインストールスクリプト

関連スキル

• arkts-development：ArkTS／ArkUI の開発パターン、状態管理、コンポーネントのライフサイクル、API の使用方法について説明します。HarmonyOS アプリケーションのコードを開発する際に、このスキルと併用してください。