vercel-storage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Vercel Storage

Vercel 存储

You are an expert in Vercel's storage options. Know which products are active, which are sunset, and when to use each.
你是 Vercel 存储选项方面的专家,了解哪些产品仍在可用、哪些已下线,以及每种存储的适用场景。

Provider Choice for Bootstrap

项目启动时的存储提供商选择

Choose storage provisioning paths in this order:
  1. Preferred: Vercel-managed Neon/Upstash through the Vercel Marketplace (
    vercel integration add ...
    or dashboard). This path auto-provisions accounts/resources and injects environment variables into the linked Vercel project.
  2. Fallback: Provider CLI/manual provisioning only when Marketplace is unavailable or you must use an existing external account.
When using fallback/manual provisioning, you must add/sync environment variables yourself and then re-run
vercel env pull .env.local --yes
locally.
请按以下优先级选择存储配置路径:
  1. 首选方案:通过 Vercel 应用市场使用 Vercel 托管的 Neon/Upstash(执行
    vercel integration add ...
    命令或在控制台操作)。该路径会自动配置账户/资源,并将环境变量注入到关联的 Vercel 项目中。
  2. 备选方案:仅当应用市场不可用,或你必须使用现有外部账户时,才通过提供商 CLI 手动配置。
使用备选/手动配置方案时,你需要自行添加/同步环境变量,然后在本地重新执行
vercel env pull .env.local --yes
命令。

Active First-Party Storage

可用的官方自研存储

Vercel Blob — File Storage

Vercel Blob — 文件存储

Fast, scalable storage for unstructured data (images, videos, documents, any files).
bash
npm install @vercel/blob
ts
import { put, del, list, get } from '@vercel/blob'

// Upload from server (public)
const blob = await put('images/photo.jpg', file, {
  access: 'public',
})
// blob.url → public URL

// Upload private file
const privateBlob = await put('docs/secret.pdf', file, {
  access: 'private',
})
// Read private file back
const privateFile = await get(privateBlob.url) // returns ReadableStream + metadata

// Client upload (up to 5 TB)
import { upload } from '@vercel/blob/client'
const blob = await upload('video.mp4', file, {
  access: 'public',
  handleUploadUrl: '/api/upload', // Your token endpoint
})

// List blobs
const { blobs } = await list()

// Conditional get with ETags
const response = await get('images/photo.jpg', {
  ifNoneMatch: previousETag,
})
if (response.statusCode === 304) {
  // Not modified, use cached version
}

// Delete
await del('images/photo.jpg')
Private Storage (public beta): Use
access: 'private'
for files that should not be publicly accessible. Read them back with
get()
. Do NOT use private access for files that need to be served publicly — it leads to slow delivery and high egress costs.
Blob Data Transfer: Vercel Blob uses two delivery strategies — Fast Data Transfer (94 cities, latency-optimized) and Blob Data Transfer (18 hubs, volume-optimized for large assets). The system automatically routes via the optimal path.
Use when: Media files, user uploads, documents, any large unstructured data.
用于非结构化数据(图片、视频、文档、任意文件)的高速可扩展存储服务。
bash
npm install @vercel/blob
ts
import { put, del, list, get } from '@vercel/blob'

// Upload from server (public)
const blob = await put('images/photo.jpg', file, {
  access: 'public',
})
// blob.url → public URL

// Upload private file
const privateBlob = await put('docs/secret.pdf', file, {
  access: 'private',
})
// Read private file back
const privateFile = await get(privateBlob.url) // returns ReadableStream + metadata

// Client upload (up to 5 TB)
import { upload } from '@vercel/blob/client'
const blob = await upload('video.mp4', file, {
  access: 'public',
  handleUploadUrl: '/api/upload', // Your token endpoint
})

// List blobs
const { blobs } = await list()

// Conditional get with ETags
const response = await get('images/photo.jpg', {
  ifNoneMatch: previousETag,
})
if (response.statusCode === 304) {
  // Not modified, use cached version
}

// Delete
await del('images/photo.jpg')
私有存储(公开测试版):对不需要公开访问的文件使用
access: 'private'
,通过
get()
方法读取。不要对需要公开提供的文件使用私有访问权限——这会导致访问速度变慢、出口费用升高。
Blob 数据传输:Vercel Blob 采用两种传输策略——高速数据传输(覆盖94个城市,针对延迟优化)和Blob 数据传输(18个枢纽节点,针对大型资产的传输量优化),系统会自动选择最优路径路由。
适用场景:媒体文件、用户上传内容、文档、任意大型非结构化数据。

Vercel Edge Config — Global Configuration

Vercel Edge Config — 全局配置存储

Ultra-low-latency key-value store for application configuration. Not a database — designed for config data that must be read instantly at the edge.
bash
npm install @vercel/edge-config
ts
import { get, getAll, has } from '@vercel/edge-config'

// Read a single value (< 1ms at the edge)
const isFeatureEnabled = await get('feature-new-ui')

// Read multiple values
const config = await getAll(['feature-new-ui', 'ab-test-variant', 'redirect-rules'])

// Check existence
const exists = await has('maintenance-mode')
Use when: Feature flags, A/B testing config, dynamic routing rules, maintenance mode toggles. Anything that must be read at the edge with near-zero latency.
Do NOT use for: User data, session state, frequently written data. Edge Config is optimized for reads, not writes.
Next.js 16:
@vercel/edge-config@^1.4.3
supports
cacheComponents
and the renamed
proxy.ts
(formerly
middleware.ts
).
超低延迟的键值存储,用于存储应用配置。它不是数据库,专为需要在边缘节点即时读取的配置数据设计。
bash
npm install @vercel/edge-config
ts
import { get, getAll, has } from '@vercel/edge-config'

// Read a single value (< 1ms at the edge)
const isFeatureEnabled = await get('feature-new-ui')

// Read multiple values
const config = await getAll(['feature-new-ui', 'ab-test-variant', 'redirect-rules'])

// Check existence
const exists = await has('maintenance-mode')
适用场景:功能开关、A/B测试配置、动态路由规则、维护模式切换,所有需要在边缘节点近乎零延迟读取的内容。
不适用场景:用户数据、会话状态、频繁写入的数据。Edge Config 针对读操作优化,而非写操作。
Next.js 16 适配
@vercel/edge-config@^1.4.3
支持
cacheComponents
以及重命名后的
proxy.ts
(原
middleware.ts
)。

Marketplace Storage (Partner-Provided)

应用市场存储(合作伙伴提供)

IMPORTANT: @vercel/postgres and @vercel/kv are SUNSET

重要提示:@vercel/postgres 和 @vercel/kv 已下线

These packages no longer exist as first-party Vercel products. Use the marketplace replacements:
这些包已不再作为 Vercel 官方产品提供,请使用应用市场的替代方案:

Neon Postgres (replaces @vercel/postgres)

Neon Postgres(替代 @vercel/postgres)

Serverless Postgres with branching, auto-scaling, and connection pooling. The driver is GA at
@neondatabase/serverless@^1.0.2
and requires Node.js 19+.
bash
npm install @neondatabase/serverless
ts
// Direct Neon usage
import { neon } from '@neondatabase/serverless'

const sql = neon(process.env.DATABASE_URL!)
const users = await sql`SELECT * FROM users WHERE id = ${userId}`

// With Drizzle ORM
import { drizzle } from 'drizzle-orm/neon-http'
import { neon } from '@neondatabase/serverless'

const sql = neon(process.env.DATABASE_URL!)
const db = drizzle(sql)
Build-time safety: The
neon()
call above throws if
DATABASE_URL
is not set. Since Next.js evaluates top-level module code at build time, this will crash
next build
when env vars aren't yet configured (e.g., first deploy before Marketplace provisioning). Use lazy initialization:
ts
// src/db/index.ts — lazy initialization (safe for build time)
import { neon } from '@neondatabase/serverless'
import { drizzle } from 'drizzle-orm/neon-http'
import * as schema from './schema'

function createDb() {
  const sql = neon(process.env.DATABASE_URL!)
  return drizzle(sql, { schema })
}

let _db: ReturnType<typeof createDb> | null = null

export function getDb() {
  if (!_db) _db = createDb()
  return _db
}
WARNING: Do NOT use JavaScript
Proxy
wrappers around the DB client.
A common pattern is wrapping
db
in a
Proxy
for lazy initialization. This breaks libraries like NextAuth/Auth.js that inspect the DB adapter object (e.g., checking method existence, iterating properties). The Proxy intercepts those checks and breaks the auth request chain, causing hangs with no error. Use a plain
getDb()
function or a simple module-level lazy
let
instead.
Drizzle Kit migrations:
drizzle-kit
and
tsx
do NOT auto-load
.env.local
. Source env vars manually or use
dotenv
:
bash
undefined
无服务器 Postgres 服务,支持分支、自动扩缩容和连接池。驱动包
@neondatabase/serverless@^1.0.2
已正式发布,要求 Node.js 19+ 版本。
bash
npm install @neondatabase/serverless
ts
// Direct Neon usage
import { neon } from '@neondatabase/serverless'

const sql = neon(process.env.DATABASE_URL!)
const users = await sql`SELECT * FROM users WHERE id = ${userId}`

// With Drizzle ORM
import { drizzle } from 'drizzle-orm/neon-http'
import { neon } from '@neondatabase/serverless'

const sql = neon(process.env.DATABASE_URL!)
const db = drizzle(sql)
构建时安全性:如果未设置
DATABASE_URL
,上述
neon()
调用会抛出错误。由于 Next.js 会在构建时评估顶层模块代码,当环境变量尚未配置时(例如在应用市场配置完成前的首次部署),这会导致
next build
崩溃。建议使用懒加载初始化:
ts
// src/db/index.ts — lazy initialization (safe for build time)
import { neon } from '@neondatabase/serverless'
import { drizzle } from 'drizzle-orm/neon-http'
import * as schema from './schema'

function createDb() {
  const sql = neon(process.env.DATABASE_URL!)
  return drizzle(sql, { schema })
}

let _db: ReturnType<typeof createDb> | null = null

export function getDb() {
  if (!_db) _db = createDb()
  return _db
}
警告:不要在数据库客户端外包裹 JavaScript
Proxy
:常见的做法是用
Proxy
包裹
db
实现懒初始化,但这会破坏 NextAuth/Auth.js 等需要检查数据库适配器对象的库(例如检查方法是否存在、遍历属性)。Proxy 会拦截这些检查,破坏认证请求链路,导致无错误提示的请求挂起。请使用纯
getDb()
函数或简单的模块级懒加载
let
变量替代。
Drizzle Kit 迁移
drizzle-kit
tsx
不会自动加载
.env.local
,需要手动引入环境变量或使用
dotenv
bash
undefined

Option 1: Source env vars before running

Option 1: Source env vars before running

source <(grep -v '^#' .env.local | sed 's/^/export /') && npx drizzle-kit push
source <(grep -v '^#' .env.local | sed 's/^/export /') && npx drizzle-kit push

Option 2: Use dotenv-cli (recommended for scripts)

Option 2: Use dotenv-cli (recommended for scripts)

npm install -D dotenv-cli npx dotenv -e .env.local -- npx drizzle-kit push npx dotenv -e .env.local -- npx tsx scripts/seed.ts

This applies to any Node script that needs Vercel-provisioned env vars — only Next.js auto-loads `.env.local`.

Install via Vercel Marketplace for automatic environment variable provisioning.
npm install -D dotenv-cli npx dotenv -e .env.local -- npx drizzle-kit push npx dotenv -e .env.local -- npx tsx scripts/seed.ts

该规则适用于所有需要 Vercel 配置的环境变量的 Node 脚本——只有 Next.js 会自动加载 `.env.local`。

通过 Vercel 应用市场安装可自动配置环境变量。

Neon CLI Fallback Notes

Neon CLI 备选方案注意事项

If you use Neon CLI as the fallback path, account/project setup is managed on Neon directly instead of through Vercel Marketplace automation.
For Vercel-managed Neon projects, CLI operations require a Neon API key; do not rely on normal browser-auth login flow alone.
如果你使用 Neon CLI 作为备选配置路径,账户/项目的设置将直接在 Neon 端管理,而非通过 Vercel 应用市场自动化处理。
对于 Vercel 托管的 Neon 项目,CLI 操作需要 Neon API 密钥,不要仅依赖常规的浏览器认证登录流程。

Upstash Redis (replaces @vercel/kv)

Upstash Redis(替代 @vercel/kv)

Serverless Redis with same Vercel billing integration.
bash
npm install @upstash/redis
ts
import { Redis } from '@upstash/redis'

const redis = Redis.fromEnv() // Uses UPSTASH_REDIS_REST_URL & TOKEN

// Basic operations
await redis.set('session:abc', { userId: '123' }, { ex: 3600 })
const session = await redis.get('session:abc')

// Rate limiting
import { Ratelimit } from '@upstash/ratelimit'
const ratelimit = new Ratelimit({
  redis,
  limiter: Ratelimit.slidingWindow(10, '10s'),
})
const { success } = await ratelimit.limit('user:123')
Install via Vercel Marketplace for automatic environment variable provisioning.
无服务器 Redis 服务,与 Vercel 计费系统打通。
bash
npm install @upstash/redis
ts
import { Redis } from '@upstash/redis'

const redis = Redis.fromEnv() // Uses UPSTASH_REDIS_REST_URL & TOKEN

// Basic operations
await redis.set('session:abc', { userId: '123' }, { ex: 3600 })
const session = await redis.get('session:abc')

// Rate limiting
import { Ratelimit } from '@upstash/ratelimit'
const ratelimit = new Ratelimit({
  redis,
  limiter: Ratelimit.slidingWindow(10, '10s'),
})
const { success } = await ratelimit.limit('user:123')
通过 Vercel 应用市场安装可自动配置环境变量。

Supabase (Marketplace Native)

Supabase(应用市场原生集成)

Full Postgres database with built-in auth, realtime subscriptions, and storage. Native Vercel Marketplace integration.
bash
npm install @supabase/supabase-js @supabase/ssr
ts
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

const { data, error } = await supabase.from('users').select('*')
Install via Vercel Marketplace:
vercel integration add supabase
全功能 Postgres 数据库,内置认证、实时订阅和存储能力,原生支持 Vercel 应用市场集成。
bash
npm install @supabase/supabase-js @supabase/ssr
ts
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

const { data, error } = await supabase.from('users').select('*')
通过 Vercel 应用市场安装:
vercel integration add supabase

Prisma ORM (Marketplace Native)

Prisma ORM(应用市场原生集成)

Type-safe ORM with auto-generated client, migrations, and Prisma Accelerate for connection pooling.
bash
npm install prisma @prisma/client
npx prisma init
ts
import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()
const users = await prisma.user.findMany()
Install via Vercel Marketplace:
vercel integration add prisma
类型安全的 ORM,提供自动生成的客户端、迁移能力,以及用于连接池的 Prisma Accelerate。
bash
npm install prisma @prisma/client
npx prisma init
ts
import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()
const users = await prisma.user.findMany()
通过 Vercel 应用市场安装:
vercel integration add prisma

MongoDB Atlas

MongoDB Atlas

Document database with flexible schemas. Available via Vercel Marketplace.
bash
npm install mongodb
ts
import { MongoClient } from 'mongodb'

const client = new MongoClient(process.env.MONGODB_URI!)
const db = client.db('myapp')
const users = await db.collection('users').find({}).toArray()
Install via Vercel Marketplace:
vercel integration add mongodb-atlas
支持灵活 schema 的文档数据库,可通过 Vercel 应用市场获取。
bash
npm install mongodb
ts
import { MongoClient } from 'mongodb'

const client = new MongoClient(process.env.MONGODB_URI!)
const db = client.db('myapp')
const users = await db.collection('users').find({}).toArray()
通过 Vercel 应用市场安装:
vercel integration add mongodb-atlas

Convex

Convex

Reactive backend-as-a-service with real-time sync, serverless functions, and file storage.
bash
npm install convex
npx convex dev
ts
import { query } from './_generated/server'
import { v } from 'convex/values'

export const getUsers = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query('users').collect()
  },
})
响应式后端即服务,提供实时同步、无服务器函数和文件存储能力。
bash
npm install convex
npx convex dev
ts
import { query } from './_generated/server'
import { v } from 'convex/values'

export const getUsers = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query('users').collect()
  },
})

Turso (libSQL)

Turso (libSQL)

Edge-native SQLite database with embedded replicas for ultra-low latency reads.
bash
npm install @libsql/client
ts
import { createClient } from '@libsql/client'

const turso = createClient({
  url: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
})

const result = await turso.execute('SELECT * FROM users')
Install via Vercel Marketplace:
vercel integration add turso
边缘原生 SQLite 数据库,内置嵌入式副本,可实现超低延迟读操作。
bash
npm install @libsql/client
ts
import { createClient } from '@libsql/client'

const turso = createClient({
  url: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
})

const result = await turso.execute('SELECT * FROM users')
通过 Vercel 应用市场安装:
vercel integration add turso

Storage Decision Matrix

存储选择决策矩阵

NeedUsePackage
File uploads, media, documentsVercel Blob
@vercel/blob
Feature flags, A/B configEdge Config
@vercel/edge-config
Relational data, SQL queriesNeon Postgres
@neondatabase/serverless
Key-value cache, sessions, rate limitingUpstash Redis
@upstash/redis
Postgres + auth + realtime + storageSupabase
@supabase/supabase-js
Type-safe ORM with migrationsPrisma
@prisma/client
Document database, flexible schemasMongoDB Atlas
mongodb
Reactive backend with real-time syncConvex
convex
Edge-native SQLite with replicasTurso
@libsql/client
Full-text searchNeon Postgres (pg_trgm) or Elasticsearch (Marketplace)varies
Vector embeddingsNeon Postgres (pgvector) or Pinecone (Marketplace)varies
需求选用方案依赖包
文件上传、媒体、文档Vercel Blob
@vercel/blob
功能开关、A/B 测试配置Edge Config
@vercel/edge-config
关系型数据、SQL 查询Neon Postgres
@neondatabase/serverless
键值缓存、会话、限流Upstash Redis
@upstash/redis
Postgres + 认证 + 实时能力 + 存储Supabase
@supabase/supabase-js
带迁移能力的类型安全 ORMPrisma
@prisma/client
文档数据库、灵活 schemaMongoDB Atlas
mongodb
带实时同步的响应式后端Convex
convex
带副本的边缘原生 SQLiteTurso
@libsql/client
全文搜索Neon Postgres (pg_trgm) 或 Elasticsearch(应用市场)不固定
向量嵌入Neon Postgres (pgvector) 或 Pinecone(应用市场)不固定

Migration Guide

迁移指南

From @vercel/postgres → Neon

从 @vercel/postgres 迁移到 Neon

diff
- import { sql } from '@vercel/postgres'
+ import { neon } from '@neondatabase/serverless'
+ const sql = neon(process.env.DATABASE_URL!)
Drop-in replacement: For minimal migration effort, use
@neondatabase/vercel-postgres-compat
which provides API-compatible wrappers for
@vercel/postgres
imports.
diff
- import { sql } from '@vercel/postgres'
+ import { neon } from '@neondatabase/serverless'
+ const sql = neon(process.env.DATABASE_URL!)
无缝替换方案:为最小化迁移工作量,可使用
@neondatabase/vercel-postgres-compat
包,它提供与
@vercel/postgres
导入兼容的 API 封装。

From @vercel/kv → Upstash Redis

从 @vercel/kv 迁移到 Upstash Redis

diff
- import { kv } from '@vercel/kv'
- await kv.set('key', 'value')
- const value = await kv.get('key')
+ import { Redis } from '@upstash/redis'
+ const redis = Redis.fromEnv()
+ await redis.set('key', 'value')
+ const value = await redis.get('key')
diff
- import { kv } from '@vercel/kv'
- await kv.set('key', 'value')
- const value = await kv.get('key')
+ import { Redis } from '@upstash/redis'
+ const redis = Redis.fromEnv()
+ await redis.set('key', 'value')
+ const value = await redis.get('key')

Installing Marketplace Storage

安装应用市场存储服务

Use the Vercel CLI or the Marketplace dashboard at
https://vercel.com/dashboard/{team}/stores
:
bash
undefined
使用 Vercel CLI 或应用市场控制台
https://vercel.com/dashboard/{team}/stores
操作:
bash
undefined

Install a storage integration (auto-provisions env vars)

安装存储集成(自动配置环境变量)

vercel integration add neon vercel integration add upstash
vercel integration add neon vercel integration add upstash

List installed integrations

列出已安装的集成

vercel integration list

Browse additional storage options at the [Vercel Marketplace](https://vercel.com/marketplace). Installing via the CLI or dashboard (`https://vercel.com/dashboard/{team}/integrations`) automatically provisions accounts, creates databases, and sets environment variables.
vercel integration list

在 [Vercel 应用市场](https://vercel.com/marketplace) 可浏览更多存储选项。通过 CLI 或控制台(`https://vercel.com/dashboard/{team}/integrations`)安装会自动配置账户、创建数据库并设置环境变量。

Official Documentation

官方文档