[ PROMPT_NODE_24138 ]
Kv API 参考
[ SKILL_DOCUMENTATION ]
# KV API 参考
## 读取操作
typescript
// 单个键 (字符串)
const value = await env.MY_KV.get("user:123");
// JSON 类型 (自动解析)
const config = await env.MY_KV.get("config", "json");
// 二进制数据的 ArrayBuffer
const buffer = await env.MY_KV.get("image", "arrayBuffer");
// 大数值的流 (Stream)
const stream = await env.MY_KV.get("large-file", "stream");
// 带缓存 TTL (最小 60秒)
const value = await env.MY_KV.get("key", { type: "text", cacheTtl: 300 });
// 批量获取 (最多 100 个键，计为 1 次操作)
const keys = ["user:1", "user:2", "user:3", "missing:key"];
const results = await env.MY_KV.get(keys);
// 返回 Map
console.log(results.get("user:1")); // "John" (如果存在)
console.log(results.get("missing:key")); // null
// 处理结果 (空值处理)
for (const [key, value] of results) {
if (value !== null) {
// 处理找到的键
console.log(`${key}: ${value}`);
}
}
// 使用泛型的 TypeScript (类型安全的 JSON 解析)
interface UserProfile { name: string; email: string; }
const profile = await env.USERS.get("user:123", "json");
// profile 被类型化为 UserProfile | null
if (profile) {
console.log(profile.name); // 类型安全访问
}
// 带类型的批量获取
const configs = await env.MY_KV.get(["config:app", "config:feature"], "json");
// Map
## 写入操作
typescript
// 基础 put
await env.MY_KV.put("key", "value");
await env.MY_KV.put("config", JSON.stringify({ theme: "dark" }));
// 带过期时间 (UNIX 时间戳)
await env.MY_KV.put("session", token, {
expiration: Math.floor(Date.now() / 1000) + 3600
});
// 带 TTL (从现在起秒数，最小 60)
await env.MY_KV.put("cache", data, { expirationTtl: 300 });
// 带元数据 (最大 1024 字节)
await env.MY_KV.put("user:profile", userData, {
metadata: { version: 2, lastUpdated: Date.now() }
});
// 组合使用
await env.MY_KV.put("temp", value, {
expirationTtl: 3600,
metadata: { temporary: true }
});
## 获取元数据
typescript
// 单个键
const result = await env.MY_KV.getWithMetadata("user:profile");
// { value: string | null, metadata: any | null }
if (result.value && result.metadata) {
const { version, lastUpdated } = result.metadata;
}
// 多个键 (批量)
const keys = ["key1", "key2", "key3"];
const results = await env.MY_KV.getWithMetadata(keys);
// 返回 Map
for (const [key, result] of
粤公网安备44030002003366号