netlify-blobs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Netlify Blobs

Netlify Blobs is zero-config object storage available from any Netlify compute (functions, edge functions, framework server routes). No provisioning required.

bash

npm install @netlify/blobs

Netlify Blobs是无需配置的对象存储服务，可从任意Netlify计算资源（函数、边缘函数、框架服务路由）中访问，无需提前配置资源。

bash

npm install @netlify/blobs

Getting a Store

获取存储实例

typescript

import { getStore } from "@netlify/blobs";

const store = getStore({ name: "my-store" });

// Use "strong" consistency when you need immediate reads after writes
const store = getStore({ name: "my-store", consistency: "strong" });

typescript

import { getStore } from "@netlify/blobs";

const store = getStore({ name: "my-store" });

// 若需要写入后立即读取，可使用“强一致性”模式
const store = getStore({ name: "my-store", consistency: "strong" });

CRUD Operations

CRUD操作

These are the only store methods. Do not invent others.

以下是存储实例仅有的方法，请勿自行扩展其他方法。

Create / Update

创建/更新

typescript

// String or binary data
await store.set("key", "value");
await store.set("key", fileBuffer);

// With metadata
await store.set("key", data, {
  metadata: { contentType: "image/png", uploadedAt: new Date().toISOString() },
});

// JSON data
await store.setJSON("key", { name: "Example", count: 42 });

typescript

// 字符串或二进制数据
await store.set("key", "value");
await store.set("key", fileBuffer);

// 附带元数据
await store.set("key", data, {
  metadata: { contentType: "image/png", uploadedAt: new Date().toISOString() },
});

// JSON数据
await store.setJSON("key", { name: "Example", count: 42 });

Read

读取

typescript

// Text (default)
const text = await store.get("key");                    // string | null

// Typed retrieval
const json = await store.get("key", { type: "json" });  // object | null
const stream = await store.get("key", { type: "stream" });
const blob = await store.get("key", { type: "blob" });
const buffer = await store.get("key", { type: "arrayBuffer" });

// With metadata
const result = await store.getWithMetadata("key");
// { data: any, etag: string, metadata: object } | null

// Metadata only (no data download)
const meta = await store.getMetadata("key");
// { etag: string, metadata: object } | null

typescript

// 文本格式（默认）
const text = await store.get("key");                    // string | null

// 指定类型读取
const json = await store.get("key", { type: "json" });  // object | null
const stream = await store.get("key", { type: "stream" });
const blob = await store.get("key", { type: "blob" });
const buffer = await store.get("key", { type: "arrayBuffer" });

// 读取数据及元数据
const result = await store.getWithMetadata("key");
// { data: any, etag: string, metadata: object } | null

// 仅读取元数据（不下载数据）
const meta = await store.getMetadata("key");
// { etag: string, metadata: object } | null

Delete

删除

typescript

await store.delete("key");

typescript

await store.delete("key");

List

列表查询

typescript

const { blobs } = await store.list();
// blobs: [{ etag: string, key: string }, ...]

// Filter by prefix
const { blobs } = await store.list({ prefix: "uploads/" });

typescript

const { blobs } = await store.list();
// blobs: [{ etag: string, key: string }, ...]

// 按前缀过滤
const { blobs } = await store.list({ prefix: "uploads/" });

Store Types

存储类型

Site-scoped (
```
getStore()
```
): Persist across all deploys. Use for most cases.
Deploy-scoped (
```
getDeployStore()
```
): Tied to a specific deploy lifecycle.

站点范围存储（
```
getStore()
```
）：在所有部署版本中持久化数据，适用于大多数场景。
部署范围存储（
```
getDeployStore()
```
）：与特定部署生命周期绑定。

Limits

限制说明

Limit	Value
Max object size	5 GB
Store name max length	64 bytes
Key max length	600 bytes

限制项	数值
单个对象最大大小	5 GB
存储实例名称最大长度	64字节
键名最大长度	600字节

Local Development

本地开发

Local dev uses a sandboxed store (separate from production). For Vite-based projects, install

@netlify/vite-plugin

to enable local Blobs access. Otherwise, use

netlify dev

Common error: "The environment has not been configured to use Netlify Blobs" — install

@netlify/vite-plugin

or run via

netlify dev

本地开发使用独立的沙箱存储（与生产环境隔离）。对于基于Vite的项目，需安装

@netlify/vite-plugin

以启用本地Blobs访问；其他项目可使用

netlify dev

命令。

常见错误：“The environment has not been configured to use Netlify Blobs”——请安装

@netlify/vite-plugin

或通过

netlify dev

运行项目。