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)
构建时安全性:上述
neon()
调用会在
DATABASE_URL
未设置时抛出错误。由于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.
与Vercel计费系统集成的无服务器Redis。
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
带自动生成客户端、迁移功能和Prisma Accelerate连接池的类型安全ORM。
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
类型安全ORM + 迁移Prisma
@prisma/client
文档型数据库、灵活SchemaMongoDB Atlas
mongodb
响应式后端 + 实时同步Convex
convex
边缘原生SQLite + 副本Turso
@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)

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

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

官方文档