macOS 環境での HarmonyOS 開発設定と頻出エラー対策

シェル環境変数の設定

macOS では使用しているシェルによって設定ファイルが異なります。まず、現在のシェルを確認します。

echo $SHELL

出力結果に応じて、以下のファイルを編集します。

  • /bin/bash の場合：~/.bash_profile
  • /bin/zsh の場合：~/.zshrc

エディタでファイルを開き、末尾に SDK のパスを通します。ユーザー名部分は各自の環境に合わせて変更してください。

export HARMONY_SDK_ROOT=/Users/${USER}/Library/Huawei/sdk
export PATH=$HARMONY_SDK_ROOT/toolchains:$PATH

保存後、以下のコマンドで設定を反映させます。

source ~/.bash_profile
# または
source ~/.zshrc

最後に、HDC ツールが認識されているか確認します。

hdc --version

OHPM パッケージマネージャの構成

OHPM CLI は鸿蒙エコシステムのサードパーティライブラリ管理に不可欠です。モジュール依存関係の解決などに使用されるため、環境変数を適切に設定する必要があります。

先ほどと同じ設定ファイルを開き、以下の行を追加します。

export HARMONY_SDK_ROOT=/Users/${USER}/Library/Huawei/
export PATH=$HARMONY_SDK_ROOT/ohpm/bin:$PATH

設定を反映させた後、バージョン表示で動作を確認します。

ohpm --version

OHPM に関する一般的なエラー

ツール使用过程中、以下のようなエラーが発生する場合があります。

インストールタスクの失敗

NPM のバージョン依存問題により、以下のようなエラーが出ることがあります。

Error: execute install task failed, component ohpm.zip.

この場合、npm ディレクトリの権限を修正することで解決できます。

sudo chown -R $(whoami):staff ~/.npm

レジストリ未設定エラー

プロジェクトビルド時にレジストリが空であると警告されるケースがあります。

ohpm ERROR: The registry is empty...

DevEco Studio の設定画面からレジストリ URL を指定する必要があります。

  1. DevEco Studio > Preferences > Build, Execution, Deployment > Ohpm を開く
  2. 「Optimize Config」を選択
  3. レジストリURLに https://repo.harmonyos.com/ohpm/ を入力し保存

設定後、プロジェクトを再ビルドしてください。

デバイスおよびエミュレータの接続問題

DevEco Studio のバージョンによっては、デバイス認識やエミュレータ起動に問題が生じることがあります。

実機接続の不安定さ

USB 接続時にデバイス管理器に表示されない場合、IDE のバージョンが原因である可能性があります。安定版ではなくベータ版、または一つ前のバージョンへダウングレードすることで改善するケースがあります。

ローカルエミュレータの起動失敗

API バージョン 6 および 9 のエミュレータが起動しない場合、OS の要件を満たしているか確認が必要です。

  • Windows: メモリ 16GB 以上推奨
  • macOS: メモリ 8GB 以上推奨。ARM 版 macOS はバージョン 12.2 以上必須

macOS 12.2 未満の場合、API バージョン 6 のエミュレータのみ利用可能です。バージョン要件を満たさない環境では、IDE のバージョン調整が必要です。

インストールエラーの解消

アプリケーションインストール時に INSTALL_PARSE_FAILED_USESDK_ERROR が発生する場合、実行デバイスと SDK のバージョンが一致していません。

compileSdkVersion と compatibleSdkVersion をデバイスの apiVersion に合わせる必要があります。ただし、単純に数値を変更するだけでは不十分な場合があります。HarmonyOS SDK のバージョンによってプロジェクト構造や対応言語が異なるためです。

  • API Version 4~7: Gradle ベース（非推奨）
  • API Version 8~9: Hvigor ベース

言語サポートもバージョンにより異なります（ArkTS, JS, Java など）。バージョン不一致によるエラーが発生した場合は、新規プロジェクト作成時に実行デバイスの API バージョンに合わせた SDK を選択することを推奨します。

デバイスの API バージョンは HDC コマンドで確認可能です。

hdc shell getprop hw_sc.build.os.apiversion

Hvigor エンジンのバージョン制約

プロジェクト実行時に以下のようなバリデーションエラーが出ることがあります。

message: 'must be > 7', instancePath: 'app.compileSdkVersion'

これは Hvigor エンジンが API Version 7 以上を要求していることを示しています。設定値がこれ未満になっている場合、エラーが発生します。Compile SDK を実行環境のバージョンに正しく対応させてください。

Harmony エミュレータでの Android アプリ実行

DevEco Studio 付属のエミュレータは安定しており、Android アプリの動作確認にも利用可能です。

エミュレータの導入

Device Manager から「New Emulator」を選択し、指示に従って作成します。

Android アプリのインストール

ADB コマンドまたは IDE の実行ボタンからインストール可能です。ただし、Harmony エミュレータのアーキテクチャは x86 であるため、Android プロジェクトの build.gradle で x86 ABI を有効にする必要があります。

タグ: HarmonyOS DevEco-Studio OHPM macOS 環境構築

6月13日 22:24 投稿

ホットタグ

©2026 異端開発室