ローカル開発

プロジェクトのディレクトリで npx wrangler dev（Cloudflare Vite plugin を使う Vite プロジェクトでは vite dev）を実行するだけで、Container と Worker の両方をローカルで動かせます。

Container 対応 Workers をローカル開発するには、まず Docker 互換の CLI と Engine がインストールされていることを確認してください。例として Docker Desktop ↗ や Colima ↗ を使えます。

開発セッションを開始すると、コンテナイメージがビルドまたはダウンロードされます。Wrangler の設定 の image 属性がローカルパスの場合は、ローカルの Dockerfile でイメージをビルドします。image 属性がイメージ参照の場合は、Cloudflare Registry、Docker Hub、Amazon ECR、Google Artifact Registry など、参照先のレジストリからイメージを取得します。

Worker のコードが新しいコンテナの作成を呼び出すと、コンテナインスタンスがローカルで起動します。リクエストはその後、正しいローカル実行中のコンテナへ自動でルーティングされます。

開発セッションが終わると、関連するコンテナインスタンスは停止します。ただしローカルイメージは削除されないので、以降のビルドで再利用できます。

Miniflare は、ローカルコンテナに Filesystem in Userspace (FUSE) に必要な Docker 権限を自動で付与します。これは wrangler dev、Cloudflare Vite plugin、Miniflare の直接利用に適用されます。

Miniflare がこれらの権限を付与するのは、ローカルの Docker デーモンが仮想マシン（VM）内で動いている場合です。macOS 上の Docker エンジンや、Windows Subsystem for Linux (WSL) 経由の Docker が含まれます。Linux では、/dev/fuse が使えるローカルの rootless Docker に対して権限を付与します。

Linux の rootful Docker は、ローカル開発時にデフォルトで FUSE をサポートしません。Docker デーモンがこれらの条件を満たさない、または検査できない場合、Miniflare は FUSE 権限を付与しません。

Wrangler または Vite で開発すると、変更を保存するたびに Worker のコードは自動で再読み込みされます。一方、コンテナ内で動くコードは再読み込みされません。

新しいコード変更でコンテナを再ビルドするには、キーボードの [r] キーを押します。再ビルドが始まり、コンテナインスタンスは新しくビルドしたイメージで再起動されます。

独自のコードウォッチャーや再読み込みの仕組みを用意したり、ローカルディレクトリをローカルコンテナイメージにマウントしてコード変更を同期したりすることもできます。できますが、組み込みの仕組みはなく、ベストプラクティスはコンテナコードで使う言語やフレームワークに依存します。

本番では、コンテナのすべてのポートに Worker からアクセスできるので、Dockerfile の EXPOSE 命令 ↗ でポートを明示する必要はありません。

ローカル開発では、アクセスするポートを Dockerfile の EXPOSE 命令で宣言する必要があります。例: ポート 4000 にアクセスする場合は EXPOSE 4000。

ポートを公開していない場合、ローカル開発では次のエラーが出ます。

The container "MyContainer" does not expose any ports. In your Dockerfile, please expose any ports you intend to connect to.

Dockerfile で公開していないポートに接続しようとすると、次のエラーが出ます。

connect(): Connection refused: container port not found. Make sure you exposed the port in your container definition.

コンテナ起動中で、まだポートが使えないときにも同じ表示になることがあります。ポートが使えるまで再試行してください。 containers パッケージ ↗ を使っている場合、この再試行ロジックは処理されます。

コンテナへの接続時に原因不明の internal error が出る場合は、コンテナエンジンが待ち受けているソケットパスに DOCKER_HOST 環境変数を設定する必要があることがあります。Wrangler または Vite は、コンテナエンジンとの通信に使う正しいソケットを自動検出しますが、うまくいかない場合はこの環境変数に適切なソケットパスを設定してください。

Cloudflare One Client や TLS 検査を行う VPN を動かしていると、Docker ビルド中の HTTPS リクエストが SSL または証明書エラーで失敗することがあります。VPN が HTTPS トラフィックを傍受し、独自の認証局で再署名するため、Docker がデフォルトではその証明書を信頼しないからです。

次のいずれかで解消できます。

• wrangler dev または wrangler deploy の実行中は Cloudflare One Client または VPN をオフにし、完了後に再度オンにします。

• 証明書を Docker のビルドコンテキストに追加します。Cloudflare One Client は、ホストマシンの NODE_EXTRA_CA_CERTS と SSL_CERT_FILE 環境変数で証明書を公開します。証明書を環境変数として Docker ビルドに渡せば、最終イメージに焼き込まずにビルド中だけ使えます。

  RUN if [ -n "$SSL_CERT_FILE" ]; then \
      cp "$SSL_CERT_FILE" /usr/local/share/ca-certificates/Custom_CA.crt && \
      update-ca-certificates; \
      fi

  Wrangler は wrangler dev または wrangler deploy 実行時に Docker を自動で呼び出します。ビルドシークレットを渡す必要がある場合は、wrangler containers push でイメージを手動ビルドして push してください。