vercel-storage
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseVercel 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:
- Preferred: Vercel-managed Neon/Upstash through the Vercel Marketplace (or dashboard). This path auto-provisions accounts/resources and injects environment variables into the linked Vercel project.
vercel integration add ... - 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 locally.
vercel env pull .env.local --yes请按以下优先级选择存储配置路径:
- 首选方案:通过 Vercel 应用市场使用 Vercel 托管的 Neon/Upstash(执行 命令或在控制台操作)。该路径会自动配置账户/资源,并将环境变量注入到关联的 Vercel 项目中。
vercel integration add ... - 备选方案:仅当应用市场不可用,或你必须使用现有外部账户时,才通过提供商 CLI 手动配置。
使用备选/手动配置方案时,你需要自行添加/同步环境变量,然后在本地重新执行 命令。
vercel env pull .env.local --yesActive First-Party Storage
可用的官方自研存储
Vercel Blob — File Storage
Vercel Blob — 文件存储
Fast, scalable storage for unstructured data (images, videos, documents, any files).
bash
npm install @vercel/blobts
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 for files that should not be publicly accessible. Read them back with . Do NOT use private access for files that need to be served publicly — it leads to slow delivery and high egress costs.
access: 'private'get()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/blobts
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-configts
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: supports and the renamed (formerly ).
@vercel/edge-config@^1.4.3cacheComponentsproxy.tsmiddleware.ts超低延迟的键值存储,用于存储应用配置。它不是数据库,专为需要在边缘节点即时读取的配置数据设计。
bash
npm install @vercel/edge-configts
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.3cacheComponentsproxy.tsmiddleware.tsMarketplace 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 and requires Node.js 19+.
@neondatabase/serverless@^1.0.2bash
npm install @neondatabase/serverlessts
// 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 call above throws if is not set. Since Next.js evaluates top-level module code at build time, this will crash when env vars aren't yet configured (e.g., first deploy before Marketplace provisioning). Use lazy initialization:
neon()DATABASE_URLnext buildts
// 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 wrappers around the DB client. A common pattern is wrapping in a 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 function or a simple module-level lazy instead.
ProxydbProxygetDb()letDrizzle Kit migrations: and do NOT auto-load . Source env vars manually or use :
drizzle-kittsx.env.localdotenvbash
undefined无服务器 Postgres 服务,支持分支、自动扩缩容和连接池。驱动包 已正式发布,要求 Node.js 19+ 版本。
@neondatabase/serverless@^1.0.2bash
npm install @neondatabase/serverlessts
// 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)构建时安全性:如果未设置 ,上述 调用会抛出错误。由于 Next.js 会在构建时评估顶层模块代码,当环境变量尚未配置时(例如在应用市场配置完成前的首次部署),这会导致 崩溃。建议使用懒加载初始化:
DATABASE_URLneon()next buildts
// 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 :常见的做法是用 包裹 实现懒初始化,但这会破坏 NextAuth/Auth.js 等需要检查数据库适配器对象的库(例如检查方法是否存在、遍历属性)。Proxy 会拦截这些检查,破坏认证请求链路,导致无错误提示的请求挂起。请使用纯 函数或简单的模块级懒加载 变量替代。
ProxyProxydbgetDb()letDrizzle Kit 迁移: 和 不会自动加载 ,需要手动引入环境变量或使用 :
drizzle-kittsx.env.localdotenvbash
undefinedOption 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/redists
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/redists
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/ssrts
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/ssrts
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 supabasePrisma 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 initts
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 initts
import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()
const users = await prisma.user.findMany()通过 Vercel 应用市场安装:
vercel integration add prismaMongoDB Atlas
MongoDB Atlas
Document database with flexible schemas. Available via Vercel Marketplace.
bash
npm install mongodbts
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 mongodbts
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-atlasConvex
Convex
Reactive backend-as-a-service with real-time sync, serverless functions, and file storage.
bash
npm install convex
npx convex devts
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 devts
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/clientts
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/clientts
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 tursoStorage Decision Matrix
存储选择决策矩阵
| Need | Use | Package |
|---|---|---|
| File uploads, media, documents | Vercel Blob | |
| Feature flags, A/B config | Edge Config | |
| Relational data, SQL queries | Neon Postgres | |
| Key-value cache, sessions, rate limiting | Upstash Redis | |
| Postgres + auth + realtime + storage | Supabase | |
| Type-safe ORM with migrations | Prisma | |
| Document database, flexible schemas | MongoDB Atlas | |
| Reactive backend with real-time sync | Convex | |
| Edge-native SQLite with replicas | Turso | |
| Full-text search | Neon Postgres (pg_trgm) or Elasticsearch (Marketplace) | varies |
| Vector embeddings | Neon Postgres (pgvector) or Pinecone (Marketplace) | varies |
| 需求 | 选用方案 | 依赖包 |
|---|---|---|
| 文件上传、媒体、文档 | Vercel Blob | |
| 功能开关、A/B 测试配置 | Edge Config | |
| 关系型数据、SQL 查询 | Neon Postgres | |
| 键值缓存、会话、限流 | Upstash Redis | |
| Postgres + 认证 + 实时能力 + 存储 | Supabase | |
| 带迁移能力的类型安全 ORM | Prisma | |
| 文档数据库、灵活 schema | MongoDB Atlas | |
| 带实时同步的响应式后端 | Convex | |
| 带副本的边缘原生 SQLite | Turso | |
| 全文搜索 | 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 which provides API-compatible wrappers for imports.
@neondatabase/vercel-postgres-compat@vercel/postgresdiff
- import { sql } from '@vercel/postgres'
+ import { neon } from '@neondatabase/serverless'
+ const sql = neon(process.env.DATABASE_URL!)
无缝替换方案:为最小化迁移工作量,可使用 包,它提供与 导入兼容的 API 封装。
@neondatabase/vercel-postgres-compat@vercel/postgresFrom @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}/storesbash
undefined使用 Vercel CLI 或应用市场控制台 操作:
https://vercel.com/dashboard/{team}/storesbash
undefinedInstall 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
官方文档
- Vercel Storage
- Vercel Blob
- Edge Config
- Vercel Marketplace — Neon, Upstash, and other storage integrations
- Integrations
- GitHub: Vercel Storage
- Vercel 存储
- Vercel Blob
- Edge Config
- Vercel 应用市场 — Neon、Upstash 及其他存储集成
- 集成服务
- GitHub: Vercel 存储