在不同 Cloudflare 账户之间迁移 KV 数据

最近，我需要将一个绑定了 KV 和 R2 对象存储的 Cloudflare Workers 服务迁移到另一个 Cloudflare 账户。虽然 Workers 和 R2 的迁移过程很直接，但 KV 数据的迁移却比预期要复杂一点。

由于 Cloudflare 的网页管理面板并未提供 KV 数据的导入导出功能，需要借助其官方命令行工具 wrangler 来完成这项任务。

安装与登录

首先，确保你的环境中已安装 Node.js，然后通过 npm 安装 wrangler，并登录到 KV 数据需要迁出的 Cloudflare 账户。

1
2
3
4
5


# 安装 wrangler
npm install -g wrangler

# 登录 Cloudflare 账户
wrangler login

导出 KV 数据

接下来，我们需要从源账户中导出所有 KV 数据。先在 Cloudflare 的管理面板中找到 KV 的 NAMESPACE_ID。

在本文发稿时，wrangler kv bulk get 命令一次最多只能获取 100 个键的值。因此，我们需要编写一个脚本，将所有的键（key）分批处理，每批 100 个。

以下是用于完整导出 KV 数据的 Bash 脚本：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53


#!/bin/bash
set -euo pipefail
set -x

NAMESPACE_ID=""
OUTPUT_FILE="kv_full_dump.json"

# 创建临时目录，用于存放中间文件
TMP_DIR=$(mktemp -d)
trap 'rm -rf "${TMP_DIR}"' EXIT

# 1. 拉取所有 key 对象（包含 metadata）
wrangler kv key list \
  --namespace-id "${NAMESPACE_ID}" \
  --remote > "${TMP_DIR}/keys.json"

# 2. 提取 key 列表到纯文本，拆分成每 100 行一组
jq '.[].name' "$TMP_DIR/keys.json" | split -l 100 - "$TMP_DIR/keys_chunk_raw_"

# 3. 再封装为 JSON 数组文件
for chunk in "$TMP_DIR"/keys_chunk_raw_*; do
  jq -s '.' "$chunk" > "$chunk.json"
done

# 4. 对每个 chunk 调用 bulk get，存成 JSON 文件
for json_chunk in "$TMP_DIR"/keys_chunk_raw_*.json; do
  wrangler kv bulk get \
    --namespace-id "$NAMESPACE_ID" --remote \
    "$json_chunk" \
    > "${json_chunk}.values.json"
    sed -i '${/^Success!$/d;}' "${json_chunk}.values.json"
done

# 5. 将所有分batch的 value 数组合并
jq -s 'add' "${TMP_DIR}"/keys_chunk_*.values.json > "$TMP_DIR/all_values_raw.json"
jq 'to_entries | map({name: .key, value: .value})' "$TMP_DIR/all_values_raw.json" > "$TMP_DIR/all_values.json"

# 6. 合并原始对象 + value，并重命名 name -> key，保留其他字段
jq --slurpfile vals "$TMP_DIR/all_values.json" '
  map(
    . as $o
    # try to find a matching object; if none, we get `null`
    | ( ($vals[0][] | select(.name == $o.name)) // null ) as $match
    # build key/value, default value to null if no match
    | $o
      + { key: $o.name
        , value: ( $match.value // null )
        }
      | del(.name)
  )
' "$TMP_DIR/keys.json" > "$OUTPUT_FILE"

echo "✅ 已导出含所有原始字段、重命名 name->key 且含 value 的完整结构到 $OUTPUT_FILE"

脚本执行成功后，会生成一个名为 kv_full_dump.json 的文件，其中包含了所有导出的数据。

导入 KV 数据

最后一步是导入数据。首先，通过 wrangler login 登录到你的数据迁移目标 Cloudflare 账户，然后使用 wrangler kv bulk put 命令将刚刚导出的 JSON 文件上传到新的 KV 命名空间中。

将下面的 <kv-namespace-id> 替换为你的目标 KV 命名空间的实际 ID。

1

wrangler kv bulk put --namespace-id <kv-namespace-id> --remote ./kv_full_dump.json

至此，KV 数据的迁移就完成了。