📦 Vercel to Cloudflare Worker Migration — Vercel工具

Migrate a Next.js + Supabase project from Vercel to Cloudflare Workers with Hyperdrive connection pooling.

Quick 开始

• Run analysis script 到 scan project:

   python3 scripts/analyze_project.py 
   

• Review migration 举报
• Run migration script:

   python3 scripts/migrate.py 
   

• Configure Hyperdrive: see references/hyperdrive-setup.md

Core Migration Steps

1. Install @opennextjs/cloudflare adapter

npm install @opennextjs/cloudflare

Update next.config.js or next.config.ts if needed.

2. Rewrite environment 变量 access

All process.env.XXX for Cloudflare bindings (Hyperdrive, KV, D1, etc.) must use getCloudflareContext():

// BEFORE (Vercel/Node.js)
const url = process.env.DATABASE_URL;
// AFTER (Cloudflare Worker)
import { getCloudflareContext } from '@opennextjs/cloudflare';
function getConnectionInfo() {
  const env = getCloudflareContext().env;
  const hyperdrive = env.HYPERDRIVE as { connectionString?: string } | undefined;
  if (hyperdrive?.connectionString) {
    return { connectionString: hyperdrive.connectionString, source: 'hyperdrive' };
  }
  // Fallback for local dev
  const local = env.CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE;
  if (local) {
    return { connectionString: local, source: 'hyperdrive-local' };
  }
  throw new Error('HYPERDRIVE is not configured');
}

3. Refactor global DB singleton 到 per-请求 pattern

// BEFORE: Global singleton
import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';
const client = postgres(process.env.DATABASE_URL!);
export const db = drizzle(client);
// AFTER: Per-request with React cache
import { cache } from 'react';
export const getDb = cache(() => {
  const { connectionString, source } = getConnectionInfo();
  return createDatabase({
    connectionString,
    enableSSL: source === 'hyperdrive' ? false : 'require',
  });
});

Then replace all import { db } with import { getDb } and add const db = getDb() at the start of each function.

4. Configure wrangler.toml

name = "my-app"
main = ".open-next/worker.js"
compatibility_date = "2024-09-23"
compatibility_flags = ["nodejs_compat"]
[[hyperdrive]]
binding = "HYPERDRIVE"
id = ""

Critical Pitfalls

• Hyperdrive 必须 connect 到 Supabase Direct 连接 (port 5432), 不 Pooler (port 6543). Hyperdrive 连接 pooler — connecting pooler-到-pooler causes errors.

• SSL 必须 已禁用 对于 Hyperdrive connections — 工作者 ↔ Hyperdrive internal network. 仅 enable SSL 对于 direct 数据库 connections (local dev, build stage).

• Cannot initialize DB 在 模块 top level — getCloudflareContext() 仅 works 期间 请求 handling, 不 在 模块 加载 时间.

• Supabase Free Tier direct 连接 IPv6 仅 — local dev 可能 失败 如果 network doesn't support IPv6. 使用 Pooler URL (port 6543) 对于 local development.

Detailed References

• Hyperdrive setup & Supabase 配置: 读取 references/hyperdrive-setup.md
• Environment 变量 patterns: 读取 references/env-patterns.md