v0.21

シミュレーションとデバッグ

はじめに

ネイティブシミュレーション環境は開発中の迅速なイテレーションを提供します。本番ビルドとは異なりシミュレーターはローカル開発サーバーに直接接続しホットリロードをサポートします。

シミュレーションモード

シミュレーションモードは開発サーバーのurlをネイティブランタイムに自動的に注入します。サーバーがまだ実行されていない場合フレームワークはサーバーを起動します。

iosシミュレーション

1dstrn simulate --ios

フレームワークはシステム上で利用可能なiosシミュレーターを検索します。既に起動しているデバイスを優先し最新の利用可能なiphoneモデルにフォールバックします。

要件:

シミュレーターはswiftランタイムとjavascriptアプリケーションの両方からのコンソール出力を表示します。rキーを押してwebviewをリロードします。qキーを押して終了します。

androidシミュレーション

1dstrn simulate --android

フレームワークは最初に接続されている実機デバイスを確認します。見つからない場合は設定されているandroid仮想デバイスを検索し最初のデバイスを自動的に起動します。

要件:

エミュレーターの起動には最大1分かかる場合があります。フレームワークはアプリケーションをインストールして起動する前にデバイスの準備が整うのを待ちます。

NOTE

androidエミュレーターは`localhost`を`10.0.2.2`にマッピングします。開発サーバーはエミュレーター内からこのホストアドレスでアクセスできる必要があります。

desktopシミュレーション

1dstrn simulate --desktop

デスクトップランタイムはtauri webviewを搭載したネイティブウィンドウを開きます。これはブラウザと同様に動作しますがブリッジを介してネイティブシステムapiにアクセスできます。

要件:

デスクトップシミュレーションは最も高速なイテレーションサイクルです。ウィンドウはリサイズ可能で標準のキーボードショートカットに応答します。コンソールにはrustランタイムとjavascript環境の両方からの出力が表示されます。

シミュレーションと本番環境の比較

シミュレーションモードと本番環境にはいくつかの重要な違いがあります:

項目 シミュレーション 本番環境
urlソース 環境変数 設定されたurl
サーバー ローカル開発 リモートまたは静的
リロード rキーで即座に実行 アプリの完全再起動
デバッグ コンソール出力有効 最小限のログ
ネットワーク localhost/10.0.2.2 本番エンドポイント

最も重要な違いはurlの解決です。シミュレーターはDSTRN_DEV_URL環境変数を介して開発サーバーのurlを受け取ります。本番ビルドはconfig/native.jsで設定されたurlを使用するかアプリケーション設定にフォールバックします。

本番ビルドでホワイトスクリーンが表示される場合は設定されたurlにアクセス可能であり有効なhtmlが返されていることを確認してください。トラブルシューティング手順については一般的な問題を参照してください。

デバッグ

フレームワークにはリアルタイムのパフォーマンス監視、ネットワークインスペクション、コンソールログ、およびdom分析を提供する統合デバッグバーが含まれています。デバッグバーはローカル開発時に自動的にアクティブ化されボトムバーインターフェースを介して切り替えることができます。

主要機能:

デバッグバーはネイティブwebviewと統合されておりios、android、desktopプラットフォーム全体で同じエクスペリエンスを提供します。

iosデバッグ

ios webviewのデバッグはsafari開発者ツールを通じて行われます:

  1. safariの環境設定で開発メニューを有効にする
  2. シミュレーターでアプリを起動する
  3. safariの開発メニューを開く
  4. シミュレータ > 対象アプリ > wkwebviewを選択する

これでjavascriptコンソール、ネットワークインスペクター、domビューアーにフルアクセスできるようになります。ブレークポイントとステップ実行デバッグは期待どおりに機能します。

swiftからのランタイムログはxcodeコンソールまたはシミュレーションコマンドを実行したターミナル出力に表示されます。

androidデバッグ

android webviewのデバッグにはchrome devtoolsを使用します:

  1. エミュレーターまたは実機デバイスでアプリを起動する
  2. chromeを開いてchrome://inspectに移動する
  3. リモートターゲットリストで対象アプリを見つける
  4. inspectをクリックしてdevtoolsを開く

webviewデバッグはデバッグビルドで自動的に有効化されます。フレームワークはlocalhostをエミュレーターのホストipにマッピングするネットワークアダプターを注入します。

ネイティブランタイムログを表示するにはadb logcatを使用します:

1adb logcat -s dstrn:V

desktopデバッグ

デスクトップアプリケーションはtauri webviewを通じてdevtoolsをサポートします。ウィンドウ内の任意の場所を右クリックして要素を調査を選択します。

コンソール出力はdevtoolsコンソールとシミュレーションを起動したターミナルの両方に表示されます。rustのログには[dstrn]プレフィックスが付きます。

一般的な問題

起動時のホワイトスクリーン

症状: アプリは起動するがコンテンツのない白い画面のみが表示される。

シミュレーションモードの場合:

開発サーバーが実行されておりアクセス可能であることを確認します:

1curl http://localhost:8250

androidの場合はエミュレーターのマッピングをテストします:

1adb shell curl http://10.0.2.2:8250

curlが成功してもアプリが白画面を表示する場合はブラウザコンソールでjavascriptエラーを確認してください。

本番ビルドの場合:

最も一般的な原因はアクセス不能または設定ミスのあるurlです。本番ビルドは開発urlを自動的には受け取りません。

ネイティブ設定を確認してください:

1// config/native.js
2export default {
3 index: 'https://your-actual-domain.com',
4};

indexがnullの場合はConfig('app.url')およびConfig('app.port')が本番サーバーを指していることを確認してください。

サーバーがネットワーク接続を必要とする場合はアプリがオフラインでも動作できるように静的フォールバックの実装を検討してください。

ネットワークリクエストの失敗

iosにおけるcorsエラー:

iosではオリジン間リクエストに対して明示的なcorsヘッダーが必要です。apiがフロントエンドと異なるドメインで実行されている場合はサーバーに適切なcorsヘッダーが含まれていることを確認してください。

androidにおける接続拒否:

androidはデフォルトで平文httpをブロックします。開発サーバーまたは本番サーバーがhttpsではなくhttpを使用している場合はマニフェストで平文トラフィックを有効にする必要があります。

フレームワークはデバッグビルドではデフォルトで平文を許可します。本番ビルドでは明示的に設定されていない限りhttpsが強制されます。

localhostにアクセスできない:

androidではlocalhostは開発マシンではなくエミュレーター自体を指します。すべてのlocalhost参照はネットワークポリフィルによって自動的に10.0.2.2に書き換えられます。

iosおよびdesktopではlocalhostは期待どおりに動作します。

静的アセットが読み込まれない

cssまたはjavascriptファイルが404エラーを返す場合はパスがサーバー設定と一致していることを確認してください。

ネイティブwebviewはページurlに対して相対urlを解決します。ページがhttps://api.example.com/からロードされアセットがhttps://cdn.example.com/から配信されている場合はhtmlで絶対urlを使用してください。

静的フォールバックサイトはバンドルルートに対してアセットを解決します。/css/dstrn.cssのようなパスはリモートモードとローカルモードの両方で正しく動作します。

javascriptエラー

エラーメッセージとスタックトレースについてはjavascriptコンソールを確認してください。フレームワークのエラーハンドラーはローカルモードで詳細なデバッグ情報を表示します。

一般的な原因:

ネイティブブリッジはすべてのプラットフォームでApp.native(またはwindow.App.native)として利用可能です。コードがネイティブ機能に依存している場合はメソッドを呼び出す前にブリッジが存在することを確認してください。

ログ出力

ネイティブランタイムは標準化されたログメッセージを出力します:

1[dstrn] loading remote: https://api.example.com
2[dstrn] webview ready
3[dstrn] load failed: network error
4[dstrn] attempting fallback

シミュレーションモードは本番環境よりも詳細に出力されます。本番環境では重大なエラーと状態変更のみがログに記録されます。

プラットフォームごとにネイティブログをフィルタリングできます:

1# ios
2xcrun simctl spawn booted log stream --predicate 'processImagePath contains "dframework"'
3
4# android
5adb logcat -s dstrn:V
6
7# desktop
8# logs appear in terminal where simulate was run