无论你使用 Wrangler 还是 Cloudflare Vite 插件 ↗,本地开发期间的数据访问工作流程都相同。不过,只有通过 Wrangler CLI 才能向本地资源填充数据。
运行 wrangler dev 或 vite ↗ 时,Miniflare会自动创建资源的本地版本,例如 KV、D1 或 R2。因此,你不需要为每项服务手动设置独立的本地实例。不过,新创建的本地资源不包含数据;你需要使用带 --local 标志的 Wrangler 命令为其填充数据。对本地资源所做的更改不会影响生产数据。
首次开始开发时,本地资源将为空。你需要使用 Wrangler CLI 为它们填充数据。
npx wrangler kv key put <KEY> <VALUE> --binding=<BINDING> --local yarn wrangler kv key put <KEY> <VALUE> --binding=<BINDING> --local pnpm wrangler kv key put <KEY> <VALUE> --binding=<BINDING> --local npx wrangler kv bulk put <FILENAME.json> --binding=<BINDING> --localyarn wrangler kv bulk put <FILENAME.json> --binding=<BINDING> --localpnpm wrangler kv bulk put <FILENAME.json> --binding=<BINDING> --localnpx wrangler r2 object put <BUCKET>/<KEY> --file=<PATH_TO_FILE> --localyarn wrangler r2 object put <BUCKET>/<KEY> --file=<PATH_TO_FILE> --localpnpm wrangler r2 object put <BUCKET>/<KEY> --file=<PATH_TO_FILE> --local你也可以包含其他元数据。
npx wrangler d1 execute <DATABASE_NAME> --command="<SQL_QUERY>" --localyarn wrangler d1 execute <DATABASE_NAME> --command="<SQL_QUERY>" --localpnpm wrangler d1 execute <DATABASE_NAME> --command="<SQL_QUERY>" --localnpx wrangler d1 execute <DATABASE_NAME> --file=./schema.sql --localyarn wrangler d1 execute <DATABASE_NAME> --file=./schema.sql --localpnpm wrangler d1 execute <DATABASE_NAME> --file=./schema.sql --localnpx wrangler flagship flags pull <APP_ID>yarn wrangler flagship flags pull <APP_ID>pnpm wrangler flagship flags pull <APP_ID>npx wrangler flagship flags create <APP_ID> new-checkout --localyarn wrangler flagship flags create <APP_ID> new-checkout --localpnpm wrangler flagship flags create <APP_ID> new-checkout --local如果要改用 cf CLI 管理本地存储,请参阅 Flagship 本地开发。
对于 Durable Objects,与 KV、D1 和 R2 不同,没有用于填充本地数据的 CLI 命令。要在本地开发期间为 Durable Objects 添加数据,你必须编写应用代码来创建 Durable Object 实例,并调用存储状态的方法。这通常涉及创建开发端点或测试路由,用所需数据初始化 Durable Objects。
默认情况下,Wrangler 和 Vite 插件都将本地绑定数据存储在同一位置:项目目录中的 .wrangler/state 文件夹。该文件夹在子目录中存储所有本地绑定的数据:KV 命名空间、R2 存储桶、D1 数据库、Durable Objects 等。
你可以随时删除 .wrangler/state 文件夹以重置本地环境,Miniflare 会在下次运行 dev 命令时重新创建它。你也可以删除 .wrangler/state 内的特定子文件夹,进行更有针对性的清理。
如果你希望为本地存储指定不同的目录,可以通过 Wrangler CLI 或在 Vite 插件配置中进行设置。
在 wrangler dev 中使用 --persist-to 标志。每次运行 dev 命令时都需要指定此标志:
npx wrangler dev --persist-to <DIRECTORY>yarn wrangler dev --persist-to <DIRECTORY>pnpm wrangler dev --persist-to <DIRECTORY>将 --local 与 --persist-to 一起使用
--local 与 --persist-to 一起使用如果你运行 wrangler dev --persist-to <DIRECTORY> 为本地数据指定自定义位置,在运行其他修改本地数据的 Wrangler 命令时,也必须包含相同的 --persist-to <DIRECTORY>(并确保包含 --local 标志)。
例如,要在本地 KV 命名空间中创建名为 test、值为 12345 的 KV 键,请运行:
npx wrangler kv key put test 12345 --binding MY_KV_NAMESPACE --local --persist-to worker-localyarn wrangler kv key put test 12345 --binding MY_KV_NAMESPACE --local --persist-to worker-localpnpm wrangler kv key put test 12345 --binding MY_KV_NAMESPACE --local --persist-to worker-local此命令:
- 在绑定
MY_KV_NAMESPACE(在 Wrangler 配置文件 中定义)中将 KV 键test设置为12345。 - 使用
--persist-to worker-local确保数据创建在 worker-local 目录中,而不是默认的.wrangler/state。 - 添加
--local标志,表示你要修改本地数据。
如果未指定 --persist-to,Wrangler 默认使用 .wrangler/state 存储本地数据。
要自定义 Vite 插件存储本地数据的位置,请在 Vite 配置文件中配置 persistState 选项:
import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";
export default defineConfig({
plugins: [
cloudflare({
persistState: { path: "./my-custom-directory" },
}),
],
});如果你希望 Wrangler 和 Vite 插件共享相同的状态,请将它们配置为使用相同的持久化路径。