Deploy Next.js 15 lên Cloudflare Workers: Hướng dẫn đầy đủ

Tạo KV namespace cho cache:

npx wrangler kv namespace create CACHE
# Sao chép ID nhận được vào wrangler.jsonc

Bước 3: Quản lý biến môi trường

Không bao giờ commit secrets vào wrangler.jsonc. Dùng Wrangler secrets:

# Thêm từng secret (sẽ hỏi giá trị interactively)
npx wrangler secret put DATABASE_URL
npx wrangler secret put NEXTAUTH_SECRET

# Kiểm tra danh sách
npx wrangler secret list

File .env.local cho dev local:

DATABASE_URL=postgresql://user:[email protected]/db?sslmode=require
NEXTAUTH_SECRET=your-dev-secret
NEXT_PUBLIC_APP_URL=http://localhost:3000

Bước 4: Kết nối Database — Neon PostgreSQL

Cloudflare Workers không hỗ trợ TCP connections truyền thống. Bạn phải dùng HTTP-based driver của Neon:

npm install @neondatabase/serverless

Kết nối cơ bản:

import { neon } from "@neondatabase/serverless";

const sql = neon(process.env.DATABASE_URL!);
const users = await sql`SELECT id, name FROM users LIMIT 10`;

Với Drizzle ORM (khuyến nghị cho production):

// lib/db.ts
import { neon } from "@neondatabase/serverless";
import { drizzle } from "drizzle-orm/neon-http";
import * as schema from "./schema";

const sql = neon(process.env.DATABASE_URL!);
export const db = drizzle(sql, { schema });

Quan trọng: Nếu đang dùng pg (node-postgres) với new Pool(...), cần migrate sang @neondatabase/serverless. Workers không có TCP socket.

Bước 5: Dev local với Workers Runtime

Đừng chỉ chạy npm run dev. Test trong V8 isolate thực sự:

# Build Next.js
npm run build

# Build cho Workers runtime
npx @opennextjs/cloudflare build

# Chạy trong Workers runtime (localhost:8787)
npx wrangler dev

Bước này rất quan trọng — nó sẽ phát hiện các lỗi runtime không xuất hiện khi chạy Node.js thuần (ví dụ: TCP connections, missing Node.js APIs).

Bước 6: Deploy lên Production

npx @opennextjs/cloudflare build
npx wrangler deploy

Output sau deploy thành công:

✅ Deployed my-nextjs-app
   https://my-nextjs-app.your-username.workers.dev

Bước 7: Custom Domain

Domain phải được quản lý trong Cloudflare DNS:

npx wrangler domains add myapp.com

Hoặc qua wrangler.jsonc:

{
  "routes": [
    {
      "pattern": "myapp.com/*",
      "zone_name": "myapp.com"
    }
  ]
}

Bước 8: CI/CD với GitHub Actions

Deploy tự động khi push lên main:

# .github/workflows/deploy.yml
name: Deploy to Cloudflare Workers

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - run: npx @opennextjs/cloudflare build
      - run: npx wrangler deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

Tạo token: Cloudflare Dashboard → My Profile → API Tokens → Create Token → chọn template "Edit Cloudflare Workers". Thêm token vào GitHub Secrets của repo.

Mẹo tối ưu hiệu suất

1. Cache responses tích cực

// app/api/products/route.ts
export async function GET() {
  const data = await getProducts();
  return Response.json(data, {
    headers: {
      "Cache-Control": "public, s-maxage=60, stale-while-revalidate=300",
    },
  });
}

2. Cloudflare KV cho session data

// Đọc từ KV cache (~1ms) trước khi query DB
const cached = await env.CACHE.get(`session:${userId}`);
if (!cached) {
  const user = await db.query.users.findFirst({ where: eq(users.id, userId) });
  await env.CACHE.put(`session:${userId}`, JSON.stringify(user), {
    expirationTtl: 3600,
  });
}

3. Giữ bundle dưới 10MB

• Tránh import toàn bộ thư viện — dùng named imports
• Phân tích với @next/bundle-analyzer
• Dùng next/dynamic cho components nặng

4. Streaming SSR cho trang lớn

import { Suspense } from "react";

export default function DashboardPage() {
  return (
    <Suspense fallback={<div>Đang tải...</div>}>
      <DataHeavyComponent />
    </Suspense>
  );
}

Troubleshooting phổ biến

Đang xây dựng MVP với Next.js? Xem thêm tại sao Next.js + TypeScript + Postgres là stack MVP tốt nhất — setup Cloudflare Workers hoàn toàn tương thích với stack này. Nếu cần kết nối thêm data pipeline, xem hướng dẫn xây dựng data pipeline với PostgreSQL và Python.