Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

ローカルデータの追加

最終更新 Markdown で表示Agent セットアップ

Wrangler と Cloudflare Vite plugin ↗ のどちらを使う場合も、ローカル開発中にデータへアクセスする手順は同じです。一方、ローカルリソースにデータを投入する操作は、Wrangler CLI でのみ行えます。

仕組み

wrangler dev または vite ↗ を実行すると、Miniflare が KV、D1、R2 などのリソースのローカル版を自動で作成します。サービスごとにローカルインスタンスを手作業で用意する必要はありません。ただし、作成直後のローカルリソースにはデータが入っていません。投入するには、--local フラグ付きの Wrangler コマンドを使います。ローカルリソースへの変更は、本番データには影響しません。

ローカルリソースへのデータ投入

開発を始めた直後、ローカルリソースは空です。Wrangler CLI でデータを投入します。

KV 名前空間

キーと値のペアを 1 件追加する

npx wrangler kv key put <KEY> <VALUE> --binding=<BINDING> --local

一括アップロード

npx wrangler kv bulk put <FILENAME.json> --binding=<BINDING> --local

R2 バケット

ファイルをアップロードする

npx wrangler r2 object put <BUCKET>/<KEY> --file=<PATH_TO_FILE> --local

そのほかのメタデータ も指定できます。

D1 データベース

SQL 文を実行する

npx wrangler d1 execute <DATABASE_NAME> --command="<SQL_QUERY>" --local

SQL ファイルを実行する

npx wrangler d1 execute <DATABASE_NAME> --file=./schema.sql --local

Durable Objects

Durable Objects には、KV、D1、R2 と異なり、ローカルデータを投入する CLI コマンドがありません。ローカル開発で Durable Objects にデータを入れるには、Durable Object インスタンスを作成し、状態を保存するメソッドを呼び出すアプリケーションコードを書きます。目的のデータを初期化する開発用エンドポイントやテスト用ルートを用意するのが一般的です。

ローカルデータの保存場所

デフォルトでは、Wrangler と Vite plugin はどちらも、プロジェクトディレクトリ内の .wrangler/state フォルダーにローカルバインディングのデータを保存します。このフォルダーは、KV 名前空間、R2 バケット、D1 データベース、Durable Objects など、すべてのローカルバインディング用のサブディレクトリにデータを格納します。

ローカルストレージの削除

.wrangler/state フォルダーはいつでも削除でき、ローカル環境をリセットできます。次に dev コマンドを実行すると、Miniflare がフォルダーを再作成します。特定のサブフォルダーだけ削除して、対象を絞ったクリーンアップもできます。

ローカルデータディレクトリの変更

ローカルストレージに別のディレクトリを使いたい場合は、Wrangler CLI または Vite plugin の設定で指定できます。

Wrangler を使う

wrangler dev に --persist-to フラグを付けます。このフラグは、dev コマンドを実行するたびに指定します。

npx wrangler dev --persist-to <DIRECTORY>

--local と --persist-to を併用する

ローカルデータの保存先を wrangler dev --persist-to <DIRECTORY> で指定した場合、ローカルデータを変更するほかの Wrangler コマンドでも、同じ --persist-to <DIRECTORY> を付けます（--local フラグも忘れずに付けます）。

たとえば、ローカルの KV 名前空間に、キー test、値 12345 を作成するには、次を実行します。

npx wrangler kv key put test 12345 --binding MY_KV_NAMESPACE --local --persist-to worker-local

このコマンドは次を行います。

  • Wrangler 設定ファイル で定義したバインディング MY_KV_NAMESPACE に、KV キー test を 12345 として設定します。
  • --persist-to worker-local により、デフォルトの .wrangler/state ではなく worker-local ディレクトリにデータを作成します。
  • --local フラグを付けて、ローカルデータを変更することを示します。

--persist-to を指定しない場合、Wrangler はローカルデータに .wrangler/state を使います。

Cloudflare Vite plugin を使う

Vite plugin のローカルデータ保存先を変更するには、Vite 設定ファイルの persistState オプション を設定します。

vite.config.jsjs
import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
	plugins: [
		cloudflare({
			persistState: { path: "./my-custom-directory" },
		}),
	],
});

ツール間で状態を共有する

Wrangler と Vite plugin で同じ状態を共有したい場合は、同じ永続化パスを使うように設定します。

役に立ちましたか？